passkit-generator
Version:
The easiest way to generate custom Apple Wallet passes in Node.js
681 lines • 25.3 kB
JavaScript
"use strict";
var _a, _b, _c;
Object.defineProperty(exports, "__esModule", { value: true });
const tslib_1 = require("tslib");
const buffer_1 = require("buffer");
const path_1 = tslib_1.__importDefault(require("path"));
const FieldsArray_1 = tslib_1.__importDefault(require("./FieldsArray"));
const Bundle_1 = tslib_1.__importStar(require("./Bundle"));
const getModelFolderContents_1 = tslib_1.__importDefault(require("./getModelFolderContents"));
const Schemas = tslib_1.__importStar(require("./schemas"));
const Signature = tslib_1.__importStar(require("./Signature"));
const Strings = tslib_1.__importStar(require("./StringsUtils"));
const Utils = tslib_1.__importStar(require("./utils"));
const Messages = tslib_1.__importStar(require("./messages"));
const propsSymbol = Symbol("props");
const localizationSymbol = Symbol("pass.l10n");
const importMetadataSymbol = Symbol("import.pass.metadata");
const createManifestSymbol = Symbol("pass.manifest");
const closePassSymbol = Symbol("pass.close");
const passTypeSymbol = Symbol("pass.type");
const certificatesSymbol = Symbol("pass.certificates");
const RegExps = {
PASS_JSON: /pass\.json/,
MANIFEST_OR_SIGNATURE: /manifest|signature/,
PERSONALIZATION: {
JSON: /personalization\.json/,
LOGO: /personalizationLogo@(?:.{2})/,
},
PASS_STRINGS: /(?<lang>[a-zA-Z-]{2,}).lproj\/pass\.strings/,
PASS_ICON: /icon(?:@\d{1}x)?/,
};
class PKPass extends Bundle_1.default {
/**
* Either create a pass from another one
* or a disk path.
*
* @param source
* @returns
*/
static async from(source, props) {
let certificates = undefined;
let buffers = undefined;
if (!source) {
throw new TypeError(Messages.format(Messages.FROM.MISSING_SOURCE, source));
}
if (source instanceof PKPass) {
/** Cloning is happening here */
certificates = source[certificatesSymbol];
buffers = {};
const buffersEntries = Object.entries(source[Bundle_1.filesSymbol]);
/** Cloning all the buffers to prevent unwanted edits */
for (let i = 0; i < buffersEntries.length; i++) {
const [fileName, contentBuffer] = buffersEntries[i];
buffers[fileName] = buffer_1.Buffer.alloc(contentBuffer.length);
contentBuffer.copy(buffers[fileName]);
}
/**
* Moving props to pass.json instead of overrides
* because many might get excluded when passing
* through validation
*/
buffers["pass.json"] = buffer_1.Buffer.from(JSON.stringify(source[propsSymbol]));
}
else {
Schemas.assertValidity(Schemas.Template, source, Messages.TEMPLATE.INVALID);
buffers = await (0, getModelFolderContents_1.default)(source.model);
certificates = source.certificates;
}
return new PKPass(buffers, certificates, props);
}
/**
* Creates a Bundle made of PKPass to be distributed
* as a `.pkpasses` zip file. Returns a Bundle instance
* so it can be outputted both as stream or as a buffer.
*
* Using this will freeze all the instances passed as
* parameter.
*
* Throws if not all the files are instance of PKPass.
*
* @param passes
*/
static pack(...passes) {
const [bundle, freezeBundle] = Bundle_1.default.freezable("application/vnd.apple.pkpasses");
for (let i = 0; i < passes.length; i++) {
const pass = passes[i];
if (!(pass instanceof PKPass)) {
throw new Error(Messages.PACK.INVALID);
}
bundle.addBuffer(`packed-pass-${i + 1}.pkpass`, pass.getAsBuffer());
}
freezeBundle();
return bundle;
}
// **************** //
// *** INSTANCE *** //
// **************** //
constructor(buffers, certificates, props) {
super("application/vnd.apple.pkpass");
this[_a] = {};
this[_b] = {};
this[_c] = undefined;
if (buffers && typeof buffers === "object") {
const buffersEntries = Object.entries(buffers);
for (let i = buffersEntries.length, buffer; (buffer = buffersEntries[--i]);) {
const [fileName, contentBuffer] = buffer;
this.addBuffer(fileName, contentBuffer);
}
}
else {
console.warn(Messages.format(Messages.INIT.INVALID_BUFFERS, typeof buffers));
}
if (props) {
/** Overrides validation and pushing in props */
const overridesValidation = Schemas.validate(Schemas.OverridablePassProps, props);
Object.assign(this[propsSymbol], overridesValidation);
}
if (certificates) {
this.certificates = certificates;
}
}
/**
* Allows changing the certificates, if needed.
* They are actually expected to be received in
* the constructor, but they can get overridden
* here for whatever purpose.
*
* When using this setter, all certificates are
* expected to be received, or an exception will
* be thrown.
*
* @param certs
*/
set certificates(certs) {
Utils.assertUnfrozen(this);
Schemas.assertValidity(Schemas.CertificatesSchema, certs, Messages.CERTIFICATES.INVALID);
this[certificatesSymbol] = certs;
}
/**
* Allows retrieving current languages
*/
get languages() {
return Object.keys(this[localizationSymbol]);
}
/**
* Allows getting an image of the props
* that are composing your pass instance.
*/
get props() {
return Utils.cloneRecursive(this[propsSymbol]);
}
/**
* Allows setting a transitType property
* for a boardingPass.
*
* @throws if current type is not "boardingPass".
* @param value
*/
set transitType(value) {
Utils.assertUnfrozen(this);
if (this.type !== "boardingPass") {
throw new TypeError(Messages.TRANSIT_TYPE.UNEXPECTED_PASS_TYPE);
}
Schemas.assertValidity(Schemas.TransitType, value, Messages.TRANSIT_TYPE.INVALID);
this[propsSymbol]["boardingPass"].transitType = value;
}
/**
* Allows getting the current transitType
* from pass props.
*
* @throws (automatically) if current type is not "boardingPass".
*/
get transitType() {
return this[propsSymbol]["boardingPass"].transitType;
}
/**
* Allows accessing to primaryFields object.
*
* @throws (automatically) if no valid pass.json
* has been parsed yet or, anyway, if current
* instance has not a valid type set yet.
*/
get primaryFields() {
return this[propsSymbol][this.type].primaryFields;
}
/**
* Allows accessing to secondaryFields object
*
* @throws (automatically) if no valid pass.json
* has been parsed yet or, anyway, if current
* instance has not a valid type set yet.
*/
get secondaryFields() {
return this[propsSymbol][this.type].secondaryFields;
}
/**
* Allows accessing to auxiliaryFields object
*
* For Typescript users: this signature allows
* in any case to add the 'row' field, but on
* runtime they are only allowed on "eventTicket"
* passes.
*
* @throws (automatically) if no valid pass.json
* has been parsed yet or, anyway, if current
* instance has not a valid type set yet.
*/
get auxiliaryFields() {
return this[propsSymbol][this.type].auxiliaryFields;
}
/**
* Allows accessing to headerFields object
*
* @throws (automatically) if no valid pass.json
* has been parsed yet or, anyway, if current
* instance has not a valid type set yet.
*/
get headerFields() {
return this[propsSymbol][this.type].headerFields;
}
/**
* Allows accessing to backFields object
*
* @throws (automatically) if no valid pass.json
* has been parsed yet or, anyway, if current
* instance has not a valid type set yet.
*/
get backFields() {
return this[propsSymbol][this.type].backFields;
}
/**
* Allows setting a pass type.
*
* **Warning**: setting a type with this setter,
* will reset all the fields (primaryFields,
* secondaryFields, headerFields, auxiliaryFields, backFields),
* both imported or manually set.
*/
set type(nextType) {
Utils.assertUnfrozen(this);
Schemas.assertValidity(Schemas.PassType, nextType, Messages.PASS_TYPE.INVALID);
/** Shut up, typescript strict mode! */
const type = nextType;
if (this.type) {
/**
* Removing reference to previous type and its content because
* we might have some differences between types. It is way easier
* to reset everything instead of making checks.
*/
this[propsSymbol][this.type] = undefined;
}
const sharedKeysPool = new Set();
this[passTypeSymbol] = type;
this[propsSymbol][type] = {
headerFields /******/: new FieldsArray_1.default(this, sharedKeysPool, Schemas.Field),
primaryFields /*****/: new FieldsArray_1.default(this, sharedKeysPool, Schemas.Field),
secondaryFields /***/: new FieldsArray_1.default(this, sharedKeysPool, Schemas.Field),
auxiliaryFields /***/: new FieldsArray_1.default(this, sharedKeysPool, type === "eventTicket" ? Schemas.FieldWithRow : Schemas.Field),
backFields /********/: new FieldsArray_1.default(this, sharedKeysPool, Schemas.Field),
transitType: undefined,
};
}
get type() {
var _d;
return (_d = this[passTypeSymbol]) !== null && _d !== void 0 ? _d : undefined;
}
// **************************** //
// *** ASSETS SETUP METHODS *** //
// **************************** //
/**
* Allows adding a new asset inside the pass / bundle with
* the following exceptions:
*
* - Empty buffers are ignored;
* - `manifest.json` and `signature` files will be ignored;
* - `pass.json` will be read validated and merged in the
* current instance, if it wasn't added previously.
* It's properties will overwrite the instance ones.
* You might loose data;
* - `pass.strings` files will be read, parsed and merged
* with the current translations. Comments will be ignored;
* - `personalization.json` will be read, validated and added.
* They will be stripped out when exporting the pass if
* it won't have NFC details or if any of the personalization
* files is missing;
*
* @param pathName
* @param buffer
*/
addBuffer(pathName, buffer) {
if (!(buffer === null || buffer === void 0 ? void 0 : buffer.length)) {
return;
}
if (RegExps.MANIFEST_OR_SIGNATURE.test(pathName)) {
return;
}
if (RegExps.PASS_JSON.test(pathName)) {
if (this[Bundle_1.filesSymbol]["pass.json"]) {
/**
* Ignoring any further addition. In a
* future we might consider merging instead
*/
return;
}
try {
this[importMetadataSymbol](validateJSONBuffer(buffer, Schemas.PassProps));
}
catch (err) {
console.warn(Messages.format(Messages.PASS_SOURCE.INVALID, err));
return;
}
/**
* Adding an empty buffer just for reference
* that we received a valid pass.json file.
* It will be reconciliated in export phase.
*/
return super.addBuffer(pathName, buffer_1.Buffer.alloc(0));
}
if (RegExps.PERSONALIZATION.JSON.test(pathName)) {
/**
* We are still allowing `personalizationLogo@XX.png`
* to be added to the bundle, but we'll delete it
* once the pass is getting closed, if needed.
*/
try {
validateJSONBuffer(buffer, Schemas.Personalize);
}
catch (err) {
console.warn(Messages.format(Messages.PERSONALIZE.INVALID, err));
return;
}
return super.addBuffer(pathName, buffer);
}
/**
* Converting Windows path to Unix path
* @example de.lproj\\icon.png => de.lproj/icon.png
*/
const normalizedPathName = pathName.replace(path_1.default.sep, "/");
/**
* If a new pass.strings file is added, we want to
* prevent it from being merged and, instead, save
* its translations for later
*/
let match;
if ((match = normalizedPathName.match(RegExps.PASS_STRINGS))) {
const [, lang] = match;
const parsedTranslations = Strings.parse(buffer).translations;
if (!parsedTranslations.length) {
return;
}
this.localize(lang, Object.fromEntries(parsedTranslations));
return;
}
return super.addBuffer(normalizedPathName, buffer);
}
/**
* Given data from a pass.json, reads them to bring them
* into the current pass instance.
*
* @param data
*/
[(_a = propsSymbol, _b = localizationSymbol, _c = passTypeSymbol, importMetadataSymbol)](data) {
const possibleTypes = [
"boardingPass",
"coupon",
"eventTicket",
"storeCard",
"generic",
];
const type = possibleTypes.find((type) => Boolean(data[type]));
const { boardingPass, coupon, storeCard, generic, eventTicket, ...otherPassData } = data;
if (Object.keys(this[propsSymbol]).length) {
console.warn(Messages.PASS_SOURCE.JOIN);
}
Object.assign(this[propsSymbol], otherPassData);
if (!type) {
if (!this[passTypeSymbol]) {
console.warn(Messages.PASS_SOURCE.UNKNOWN_TYPE);
}
}
else {
this.type = type;
const { headerFields = [], primaryFields = [], secondaryFields = [], auxiliaryFields = [], backFields = [], transitType, } = data[type] || {};
this.headerFields.push(...headerFields);
this.primaryFields.push(...primaryFields);
this.secondaryFields.push(...secondaryFields);
this.auxiliaryFields.push(...auxiliaryFields);
this.backFields.push(...backFields);
if (this.type === "boardingPass") {
this.transitType = transitType;
}
}
}
/**
* Creates the manifest starting from files
* added to the bundle
*/
[createManifestSymbol]() {
const manifest = Object.entries(this[Bundle_1.filesSymbol]).reduce((acc, [fileName, buffer]) => ({
...acc,
[fileName]: Signature.createHash(buffer),
}), {});
return buffer_1.Buffer.from(JSON.stringify(manifest));
}
/**
* Applies the last validation checks against props,
* applies the props to pass.json and creates l10n
* files and folders and creates manifest and
* signature files
*/
[closePassSymbol]() {
if (!this.type) {
throw new TypeError(Messages.CLOSE.MISSING_TYPE);
}
const fileNames = Object.keys(this[Bundle_1.filesSymbol]);
const passJson = buffer_1.Buffer.from(JSON.stringify(this[propsSymbol]));
super.addBuffer("pass.json", passJson);
if (!fileNames.some((fileName) => RegExps.PASS_ICON.test(fileName))) {
console.warn(Messages.CLOSE.MISSING_ICON);
}
// *********************************** //
// *** LOCALIZATION FILES CREATION *** //
// *********************************** //
const localizationEntries = Object.entries(this[localizationSymbol]);
for (let i = localizationEntries.length - 1; i >= 0; i--) {
const [lang, translations] = localizationEntries[i];
const stringsFile = Strings.create(translations);
if (stringsFile.length) {
super.addBuffer(`${lang}.lproj/pass.strings`, stringsFile);
}
}
// *********************** //
// *** PERSONALIZATION *** //
// *********************** //
const meetsPersonalizationRequirements = Boolean(this[propsSymbol]["nfc"] &&
this[Bundle_1.filesSymbol]["personalization.json"] &&
fileNames.find((file) => RegExps.PERSONALIZATION.LOGO.test(file)));
if (!meetsPersonalizationRequirements) {
/**
* Looking for every personalization file
* and removing it
*/
for (let i = 0; i < fileNames.length; i++) {
if (fileNames[i].includes("personalization")) {
console.warn(Messages.format(Messages.CLOSE.PERSONALIZATION_REMOVED, fileNames[i]));
delete this[Bundle_1.filesSymbol][fileNames[i]];
}
}
}
// ******************************** //
// *** BOARDING PASS VALIDATION *** //
// ******************************** //
if (this.type === "boardingPass" && !this.transitType) {
throw new TypeError(Messages.CLOSE.MISSING_TRANSIT_TYPE);
}
// ****************************** //
// *** SIGNATURE AND MANIFEST *** //
// ****************************** //
const manifestBuffer = this[createManifestSymbol]();
super.addBuffer("manifest.json", manifestBuffer);
const signatureBuffer = Signature.create(manifestBuffer, this[certificatesSymbol]);
super.addBuffer("signature", signatureBuffer);
}
// ************************* //
// *** EXPORTING METHODS *** //
// ************************* //
/**
* Exports the pass as a zip buffer. When this method
* is invoked, the bundle will get frozen and, thus,
* no files will be allowed to be added any further.
*
* @returns
*/
getAsBuffer() {
if (!this.isFrozen) {
this[closePassSymbol]();
}
return super.getAsBuffer();
}
/**
* Exports the pass as a zip stream. When this method
* is invoked, the bundle will get frozen and, thus,
* no files will be allowed to be added any further.
*
* @returns
*/
getAsStream() {
if (!this.isFrozen) {
this[closePassSymbol]();
}
return super.getAsStream();
}
/**
* Exports the pass as a list of file paths and buffers.
* When this method is invoked, the bundle will get
* frozen and, thus, no files will be allowed to be
* added any further.
*
* This allows developers to choose a different way
* of serving, analyzing or zipping the file, outside the
* default compression system.
*
* @returns a frozen object containing files paths as key
* and Buffers as content.
*/
getAsRaw() {
if (!this.isFrozen) {
this[closePassSymbol]();
}
return super.getAsRaw();
}
// ************************** //
// *** DATA SETUP METHODS *** //
// ************************** //
/**
* Allows to add a localization details to the
* final bundle with some translations.
*
* If the language already exists, translations will be
* merged with the existing ones.
*
* Setting `translations` to `null` fully deletes a language,
* its translations and its files.
*
* @see https://developer.apple.com/documentation/walletpasses/creating_the_source_for_a_pass#3736718
* @param lang
* @param translations
*/
localize(lang, translations) {
var _d;
var _e;
Utils.assertUnfrozen(this);
if (typeof lang !== "string") {
throw new TypeError(Messages.format(Messages.LANGUAGES.INVALID_LANG, typeof lang));
}
if (translations === null) {
delete this[localizationSymbol][lang];
const allFilesKeys = Object.keys(this[Bundle_1.filesSymbol]);
const langFolderIdentifier = `${lang}.lproj`;
for (let i = allFilesKeys.length - 1; i >= 0; i--) {
const filePath = allFilesKeys[i];
if (filePath.startsWith(langFolderIdentifier)) {
delete this[Bundle_1.filesSymbol][filePath];
}
}
return;
}
if (!translations || !Object.keys(translations).length) {
console.warn(Messages.format(Messages.LANGUAGES.NO_TRANSLATIONS, lang));
return;
}
(_d = (_e = this[localizationSymbol])[lang]) !== null && _d !== void 0 ? _d : (_e[lang] = {});
if (typeof translations === "object" && !Array.isArray(translations)) {
Object.assign(this[localizationSymbol][lang], translations);
}
}
/**
* Allows to specify an expiration date for the pass.
*
* Pass `null` to remove the expiration date.
*
* @param date
* @throws if pass is frozen due to previous export
* @returns
*/
setExpirationDate(date) {
Utils.assertUnfrozen(this);
if (date === null) {
delete this[propsSymbol]["expirationDate"];
return;
}
try {
this[propsSymbol]["expirationDate"] = Utils.processDate(date);
}
catch (err) {
throw new TypeError(Messages.format(Messages.DATE.INVALID, "expirationDate", date));
}
}
setBeacons(...beacons) {
Utils.assertUnfrozen(this);
if (beacons[0] === null) {
delete this[propsSymbol]["beacons"];
return;
}
this[propsSymbol]["beacons"] = Schemas.filterValid(Schemas.Beacon, beacons);
}
setLocations(...locations) {
Utils.assertUnfrozen(this);
if (locations[0] === null) {
delete this[propsSymbol]["locations"];
return;
}
this[propsSymbol]["locations"] = Schemas.filterValid(Schemas.Location, locations);
}
/**
* Allows setting a relevant date in which the OS
* should show this pass.
*
* Pass `null` to remove relevant date from this pass.
*
* @param {Date | null} date
* @throws if pass is frozen due to previous export
*/
setRelevantDate(date) {
Utils.assertUnfrozen(this);
if (date === null) {
delete this[propsSymbol]["relevantDate"];
return;
}
try {
this[propsSymbol]["relevantDate"] = Utils.processDate(date);
}
catch (err) {
throw new TypeError(Messages.format(Messages.DATE.INVALID, "relevantDate", date));
}
}
setBarcodes(...barcodes) {
Utils.assertUnfrozen(this);
if (!barcodes.length) {
return;
}
if (barcodes[0] === null) {
delete this[propsSymbol]["barcodes"];
return;
}
let finalBarcodes;
if (typeof barcodes[0] === "string") {
/**
* A string has been received instead of objects. We can
* only auto-fill them all with the same data.
*/
const supportedFormats = [
"PKBarcodeFormatQR",
"PKBarcodeFormatPDF417",
"PKBarcodeFormatAztec",
"PKBarcodeFormatCode128",
];
finalBarcodes = supportedFormats.map((format) => Schemas.validate(Schemas.Barcode, {
format,
message: barcodes[0],
}));
}
else {
finalBarcodes = Schemas.filterValid(Schemas.Barcode, barcodes);
}
this[propsSymbol]["barcodes"] = finalBarcodes;
}
/**
* Allows to specify details to make this, an
* NFC-capable pass.
*
* Pass `null` as parameter to remove it at all.
*
* @see https://developer.apple.com/documentation/walletpasses/pass/nfc
* @param data
* @throws if pass is frozen due to previous export
* @returns
*/
setNFC(nfc) {
var _d;
Utils.assertUnfrozen(this);
if (nfc === null) {
delete this[propsSymbol]["nfc"];
return;
}
this[propsSymbol]["nfc"] =
(_d = Schemas.validate(Schemas.NFC, nfc)) !== null && _d !== void 0 ? _d : undefined;
}
}
exports.default = PKPass;
function validateJSONBuffer(buffer, schema) {
let contentAsJSON;
try {
contentAsJSON = JSON.parse(buffer.toString("utf8"));
}
catch (err) {
throw new TypeError(Messages.JSON.INVALID);
}
return Schemas.validate(schema, contentAsJSON);
}
//# sourceMappingURL=PKPass.js.map