This package has been deprecated

    Author message:

    WARNING: This project has been renamed to @walletpass/pass-js. Install using @walletpass/pass-js instead.

    @destinationstransfers/passkit
    TypeScript icon, indicating that this package has built-in type declarations

    6.6.1 • Public • Published

    npm (scoped) codecov Build Status Known Vulnerabilities DeepScan grade Reliability Rating Lines of Code Maintainability Rating tested with jest install size Language grade: JavaScript

    Apple Wallet logo

    @destinationstransfers/passkit

    A Node.js library for generating Apple Wallet passes with localizations, NFC and web service push updates support. Written in Typescript.




    Installation

    Install with NPM or yarn:

    npm install @destinationstransfers/passkit --save
     
    yarn add @destinationstransfers/passkit

    Get your certificates

    To start with, you'll need a certificate issued by the iOS Provisioning Portal. You need one certificate per Pass Type ID.

    After adding this certificate to your Keychain, you need to export it as a .p12 file first, then convert that file into a .pem file using the passkit-keys command:

    ./bin/passkit-keys ./pathToKeysFolder

    and copy it into the keys directory.

    The Apple Worldwide Developer Relations Certification Authority certificate is not needed anymore since it is already included in this package.

    Start with a template

    Start with a template. A template has all the common data fields that will be shared between your passes.

    const { Template } = require("@destinationstransfers/passkit");
     
    // Create a Template from local folder, see __test__/resources/passes for examples
    // .load will load all fields from pass.json,
    // as well as all images and com.example.passbook.pem file as key
    // and localization string too
    const template = await Template.load(
      "./path/to/templateFolder",
      "secretKeyPasswod"
    );
     
    // or
    // create a Template from a Buffer with ZIP content
    const s3 = new AWS.S3({ apiVersion: "2006-03-01", region: "us-west-2" });
    const s3file = await s3
      .getObject({
        Bucket: "bucket",
        Key: "pass-template.zip"
      })
      .promise();
    const template = await Template.fromBuffer(s3file.Body);
     
    // or create it manually
    const template = new Template("coupon", {
      passTypeIdentifier: "pass.com.example.passbook",
      teamIdentifier: "MXL",
      backgroundColor: "red",
      sharingProhibited: true
    });
    await template.images.add("icon", iconPngFileBuffer)
                         .add("logo", pathToLogoPNGfile)

    The first argument is the pass style (coupon, eventTicket, etc), and the second optional argument has any fields you want to set on the template.

    You can access template fields directly, or from chained accessor methods, e.g:

    template.passTypeIdentifier = "pass.com.example.passbook";
    template.teamIdentifier = "MXL";

    The following template fields are required:

    • passTypeIdentifier - The Apple Pass Type ID, which has the prefix pass.
    • teamIdentifier - May contain an I

    You can set any available fields either on a template or pass instance, such as: backgroundColor, foregroundColor, labelColor, logoText, organizationName, suppressStripShine and webServiceURL.

    In addition, you need to tell the template where to find the key file:

    await template.loadCertificate(
      "/etc/passbook/certificate_and_key.pem",
      "secret"
    );
    // or set them as strings
    template.setCertificate(pemEncodedPassCertificate);
    template.setPrivateKey(pemEncodedPrivateKey, optionalKeyPassword);

    If you have images that are common to all passes, you may want to specify them once in the template:

    // specify a single image with specific density and localization
    await pass.images.add("icon", iconFilename, "2x", "ru");
    // load all appropriate images in all densities and localizations
    await template.images.load("./images");

    You can add the image itself or a Buffer. Image format is enforced to be PNG.

    Alternatively, if you have one directory containing the template file pass.json, the key com.example.passbook.pem and all the needed images, you can just use this single command:

    const template = await Template.load(
      "./path/to/templateFolder",
      "secretKeyPasswod"
    );

    Create your pass

    To create a new pass from a template:

    const pass = template.createPass({
      serialNumber: "123456",
      description: "20% off"
    });

    Just like the template, you can access pass fields directly, e.g:

    pass.serialNumber = "12345";
    pass.description = "20% off";

    In the JSON specification, structure fields (primary fields, secondary fields, etc) are represented as arrays, but items must have distinct key properties. Le sigh.

    To make it easier, you can use methods of standard Map object or add that will do the logical thing. For example, to add a primary field:

    pass.primaryFields.add({ key: "time", label: "Time", value: "10:00AM" });

    To get one or all fields:

    const dateField = pass.primaryFields.get("date");
    for (const [key, { value }] of pass.primaryFields.entries()) {
      // ...
    }

    To remove one or all fields:

    pass.primaryFields.delete("date");
    pass.primaryFields.clear();

    Adding images to a pass is the same as adding images to a template (see above).

    Working with Dates

    If you have dates in your fields make sure they are in ISO 8601 format with timezone or a Date instance. For example:

    const { constants } = require('@destinationstransfers/passkit');
     
    pass.primaryFields.add({ key: "updated", label: "Updated at", value: new Date(), dateStyle: constants.dateTimeFormat.SHORT, timeStyle: constants.dateTimeFormat.SHORT });
     
    // there is also a helper setDateTime method
    pass.auxiliaryFields.setDateTime(
      'serviceDate',
      'DATE',
      serviceMoment.toDate(),
      {
        dateStyle: constants.dateTimeFormat.MEDIUM,
        timeStyle: constants.dateTimeFormat.NONE,
        changeMessage: 'Service date changed to %@.',
      },
    );
    // main fields also accept Date objects
    pass.relevantDate = new Date(2020, 1, 1, 10, 0);
    template.expirationDate = new Date(2020, 10, 10, 10, 10);

    Localizations

    This library fully supports both string localization and/or images localization:

    // everything from template
    // will load all localized images and strings from folders like ru.lproj/ or fr-CA.lproj/
    await template.load(folderPath);
     
    // Strings
     
    pass.localizations
      .add("en-GB", {
        GATE: "GATE",
        DEPART: "DEPART",
        ARRIVE: "ARRIVE",
        SEAT: "SEAT",
        PASSENGER: "PASSENGER",
        FLIGHT: "FLIGHT"
      })
      .add("ru", {
        GATE: "ВЫХОД",
        DEPART: "ВЫЛЕТ",
        ARRIVE: "ПРИЛЁТ",
        SEAT: "МЕСТО",
        PASSENGER: "ПАССАЖИР",
        FLIGHT: "РЕЙС"
      });
     
    // Images
     
    await template.images.add(
      "logo" | "icon" | etc,
      imageFilePathOrBufferWithPNGdata,
      "1x" | "2x" | "3x" | undefined,
      "ru"
    );

    Localization applies for all fields' label and value. There is a note about that in documentation.

    Generate the file

    To generate a file:

    const buf = await pass.asBuffer();
    await fs.writeFile("pathToPass.pass", buf);

    You can send the buffer directly to an HTTP server response:

    app.use(async (ctx, next) => {
      ctx.status = 200;
      ctx.type = passkit.constants.PASS_MIME_TYPE;
      ctx.body = await pass.asBuffer();
    });

    Troubleshooting with Console app

    If the pass file generates without errors but you aren't able to open your pass on an iPhone, plug the iPhone into a Mac with macOS 10.14+ and open the 'Console' application. On the left, you can select your iPhone. You will then be able to inspect any errors that occur while adding the pass.

    Credits

    This projects started as fork of assaf/node-passbook. Since version 5.0 our module is not API compatible, please see Releases for more information.

    • Targeting Node >= 10 and rewritten in Typescript, removing deprecated calls (new Buffer, etc)
    • Replaces openssl spawning with native Javascript RSA implementation (via node-forge)
    • Includes Template.pushUpdates(pushToken) that sends APN update request for a given pass type to a pushToken (get pushToken at your PassKit Web Service implementation)
    • Adds constants for dictionary fields string values
    • Migrated tests to Jest
    • Increased test coverage
    • Adds strict dictionary fields values validation (where possible) to prevent errors earlier
    • Adding support for geolocation fields and Beacon fields
    • Adding easy template and localization load from JSON file
    • We use it in production at Transfers.do

    Install

    npm i @destinationstransfers/passkit

    DownloadsWeekly Downloads

    2,066

    Version

    6.6.1

    License

    MIT

    Unpacked Size

    129 kB

    Total Files

    42

    Last publish

    Collaborators

    • tinovyatkin