{"id":19686661,"url":"https://github.com/tinovyatkin/pass-js","last_synced_at":"2025-05-16T14:09:12.263Z","repository":{"id":39725535,"uuid":"99531365","full_name":"tinovyatkin/pass-js","owner":"tinovyatkin","description":"Apple Wallet Passes generating library for Node.JS","archived":false,"fork":false,"pushed_at":"2024-07-18T07:54:33.000Z","size":4053,"stargazers_count":713,"open_issues_count":47,"forks_count":83,"subscribers_count":12,"default_branch":"master","last_synced_at":"2025-05-15T00:36:58.912Z","etag":null,"topics":["apple","apple-pass","ios","nodejs","pass","passkit","wallet"],"latest_commit_sha":null,"homepage":"","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/tinovyatkin.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":".github/FUNDING.yml","license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null},"funding":{"github":"tinovyatkin"}},"created_at":"2017-08-07T03:05:33.000Z","updated_at":"2025-05-09T07:31:57.000Z","dependencies_parsed_at":"2023-09-29T19:56:21.062Z","dependency_job_id":"d7dce588-3269-4502-bd69-bcf2a76e739b","html_url":"https://github.com/tinovyatkin/pass-js","commit_stats":null,"previous_names":["walletpass/pass-js","destinationstransfers/passkit"],"tags_count":53,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tinovyatkin%2Fpass-js","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tinovyatkin%2Fpass-js/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tinovyatkin%2Fpass-js/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tinovyatkin%2Fpass-js/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/tinovyatkin","download_url":"https://codeload.github.com/tinovyatkin/pass-js/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":254544157,"owners_count":22088808,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["apple","apple-pass","ios","nodejs","pass","passkit","wallet"],"created_at":"2024-11-11T18:29:42.252Z","updated_at":"2025-05-16T14:09:07.254Z","avatar_url":"https://github.com/tinovyatkin.png","language":"TypeScript","funding_links":["https://github.com/sponsors/tinovyatkin","https://opencollective.com/walletpass/contribute"],"categories":[],"sub_categories":[],"readme":"[![npm (scoped)](https://img.shields.io/npm/v/@walletpass/pass-js.svg)](https://www.npmjs.com/package/@walletpass/pass-js) [![codecov](https://codecov.io/gh/walletpass/pass-js/branch/master/graph/badge.svg)](https://codecov.io/gh/walletpass/pass-js)\n[![Known Vulnerabilities](https://snyk.io/test/github/walletpass/pass-js/badge.svg?targetFile=package.json)](https://snyk.io/test/github/walletpass/pass-js?targetFile=package.json) [![Maintainability Rating](https://sonarcloud.io/api/project_badges/measure?project=walletpass_pass-js\u0026metric=sqale_rating)](https://sonarcloud.io/dashboard?id=walletpass_pass-js) [![tested with jest](https://img.shields.io/badge/tested_with-jest-99424f.svg)](https://github.com/facebook/jest) [![install size](https://packagephobia.now.sh/badge?p=@walletpass/pass-js)](https://packagephobia.now.sh/result?p=@walletpass/pass-js)\n\n\n\u003cimg src=\"https://docs-assets.developer.apple.com/published/c104c9bff0/841b02dd-b78c-4cad-8da4-700761d34e14.png\" alt=\"Apple Wallet logo\" width=\"216\" height=\"216\" align=\"left\"\u003e\n\n# @walletpass/pass-js\n\n\u003cp align=\"center\"\u003eA Node.js library for generating Apple Wallet passes with localizations, NFC and web service push updates support. Written in Typescript.\u003c/p\u003e\n\n\u003cbr\u003e\u003cbr\u003e\u003cbr\u003e\n\n\n# Installation\n\nInstall with `NPM` or `yarn`:\n```sh\nnpm install @walletpass/pass-js --save\n\nyarn add @walletpass/pass-js\n```\n\n\n\n# Get your certificates\n\nTo start with, you'll need a certificate issued by [the iOS Provisioning\nPortal](https://developer.apple.com/ios/manage/passtypeids/index.action). You\nneed one certificate per Pass Type ID.\n\nAfter adding this certificate to your Keychain, you need to export it as a\n`.p12` file first (go to Keychain Access, My Certificates and right-click to export), then convert that file into a `.pem` file using the `passkit-keys` command:\n\n```sh\n./bin/passkit-keys ./pathToKeysFolder\n```\nor openssl\n```sh\nopenssl pkcs12 -in \u003cexported_cert_and_private_key\u003e.p12 -clcerts -out com.example.passbook.pem -passin pass:\u003cprivate_key_password\u003e\n```\n\nand copy it into the keys directory.\n\nThe [Apple Worldwide Developer Relations Certification\nAuthority](https://www.apple.com/certificateauthority/) certificate is not needed anymore since it is already included in this package.\n\n# Start with a template\n\nStart with a template. A template has all the common data fields that will be\nshared between your passes.\n\n```js\nconst { Template } = require(\"@walletpass/pass-js\");\n\n// Create a Template from local folder, see __test__/resources/passes for examples\n// .load will load all fields from pass.json,\n// as well as all images and com.example.passbook.pem file as key\n// and localization string too\nconst template = await Template.load(\n  \"./path/to/templateFolder\",\n  \"secretKeyPasswod\"\n);\n\n// or\n// create a Template from a Buffer with ZIP content\nconst s3 = new AWS.S3({ apiVersion: \"2006-03-01\", region: \"us-west-2\" });\nconst s3file = await s3\n  .getObject({\n    Bucket: \"bucket\",\n    Key: \"pass-template.zip\"\n  })\n  .promise();\nconst template = await Template.fromBuffer(s3file.Body);\n\n// or create it manually\nconst template = new Template(\"coupon\", {\n  passTypeIdentifier: \"pass.com.example.passbook\",\n  teamIdentifier: \"MXL\",\n  backgroundColor: \"red\",\n  sharingProhibited: true\n});\nawait template.images.add(\"icon\", iconPngFileBuffer)\n                     .add(\"logo\", pathToLogoPNGfile)\n```\n\nThe first argument is the pass style (`coupon`, `eventTicket`, etc), and the\nsecond optional argument has any fields you want to set on the template.\n\nYou can access template fields directly, or from chained accessor methods, e.g:\n\n```js\ntemplate.passTypeIdentifier = \"pass.com.example.passbook\";\ntemplate.teamIdentifier = \"MXL\";\n```\n\nThe following template fields are required:\n\n- `passTypeIdentifier` - The Apple Pass Type ID, which has the prefix `pass.`\n- `teamIdentifier` - May contain an I\n\nYou can set any available fields either on a template or pass instance, such as: `backgroundColor`,\n`foregroundColor`, `labelColor`, `logoText`, `organizationName`,\n`suppressStripShine` and `webServiceURL`.\n\nIn addition, you need to tell the template where to find the key file:\n\n```js\nawait template.loadCertificate(\n  \"/etc/passbook/certificate_and_key.pem\",\n  \"secret\"\n);\n// or set them as strings\ntemplate.setCertificate(pemEncodedPassCertificate);\ntemplate.setPrivateKey(pemEncodedPrivateKey, optionalKeyPassword);\n```\n\nIf you have images that are common to all passes, you may want to specify them once in the template:\n\n```js\n// specify a single image with specific density and localization\nawait pass.images.add(\"icon\", iconFilename, \"2x\", \"ru\");\n// load all appropriate images in all densities and localizations\nawait template.images.load(\"./images\");\n```\n\nYou can add the image itself or a `Buffer`. Image format is enforced to be **PNG**.\n\nAlternatively, if you have one directory containing the template file `pass.json`, the key\n`com.example.passbook.pem` and all the needed images, you can just use this single command:\n\n```js\nconst template = await Template.load(\n  \"./path/to/templateFolder\",\n  \"secretKeyPasswod\"\n);\n```\n\nYou can use the options parameter of the template factory functions to set the `allowHttp` property. This enables you to use a `webServiceUrl` in your `pass.json` that uses the HTTP protocol instead of HTTPS for development purposes:\n\n```js\nconst template = await Template.load(\n  \"./path/to/templateFolder\",\n  \"secretKeyPasswod\",\n  {\n    allowHttp: true,\n  },\n);\n```\n\n# Create your pass\n\nTo create a new pass from a template:\n\n```js\nconst pass = template.createPass({\n  serialNumber: \"123456\",\n  description: \"20% off\"\n});\n```\n\nJust like the template, you can access pass fields directly, e.g:\n\n```js\npass.serialNumber = \"12345\";\npass.description = \"20% off\";\n```\n\nIn the JSON specification, structure fields (primary fields, secondary fields,\netc) are represented as arrays, but items must have distinct key properties. Le\nsigh.\n\nTo make it easier, you can use methods of standard Map object or `add` that\nwill do the logical thing. For example, to add a primary field:\n\n```js\npass.primaryFields.add({ key: \"time\", label: \"Time\", value: \"10:00AM\" });\n```\n\nTo get one or all fields:\n\n```js\nconst dateField = pass.primaryFields.get(\"date\");\nfor (const [key, { value }] of pass.primaryFields.entries()) {\n  // ...\n}\n```\n\nTo remove one or all fields:\n\n```js\npass.primaryFields.delete(\"date\");\npass.primaryFields.clear();\n```\n\nAdding images to a pass is the same as adding images to a template (see above).\n\n# Working with Dates\nIf you have [dates in your fields](https://developer.apple.com/library/archive/documentation/UserExperience/Reference/PassKit_Bundle/Chapters/FieldDictionary.html#//apple_ref/doc/uid/TP40012026-CH4-SW6) make sure they are in ISO 8601 format with timezone or a `Date` instance. \n For example:\n\n```js\nconst { constants } = require('@walletpass/pass-js');\n\npass.primaryFields.add({ key: \"updated\", label: \"Updated at\", value: new Date(), dateStyle: constants.dateTimeFormat.SHORT, timeStyle: constants.dateTimeFormat.SHORT });\n\n// there is also a helper setDateTime method\npass.auxiliaryFields.setDateTime(\n  'serviceDate',\n  'DATE',\n  serviceMoment.toDate(),\n  {\n    dateStyle: constants.dateTimeFormat.MEDIUM,\n    timeStyle: constants.dateTimeFormat.NONE,\n    changeMessage: 'Service date changed to %@.',\n  },\n);\n// main fields also accept Date objects\npass.relevantDate = new Date(2020, 1, 1, 10, 0);\ntemplate.expirationDate = new Date(2020, 10, 10, 10, 10);\n```\n\n# Localizations\n\nThis library fully supports both [string localization](https://developer.apple.com/library/archive/documentation/UserExperience/Conceptual/PassKit_PG/Creating.html#//apple_ref/doc/uid/TP40012195-CH4-SW54) and/or [images localization](https://developer.apple.com/library/archive/documentation/UserExperience/Conceptual/PassKit_PG/Creating.html#//apple_ref/doc/uid/TP40012195-CH4-SW1):\n\n```js\n// everything from template\n// will load all localized images and strings from folders like ru.lproj/ or fr-CA.lproj/\nawait template.load(folderPath);\n\n// Strings\n\npass.localization\n  .add(\"en-GB\", {\n    GATE: \"GATE\",\n    DEPART: \"DEPART\",\n    ARRIVE: \"ARRIVE\",\n    SEAT: \"SEAT\",\n    PASSENGER: \"PASSENGER\",\n    FLIGHT: \"FLIGHT\"\n  })\n  .add(\"ru\", {\n    GATE: \"ВЫХОД\",\n    DEPART: \"ВЫЛЕТ\",\n    ARRIVE: \"ПРИЛЁТ\",\n    SEAT: \"МЕСТО\",\n    PASSENGER: \"ПАССАЖИР\",\n    FLIGHT: \"РЕЙС\"\n  });\n\n// Images\n\nawait template.images.add(\n  \"logo\" | \"icon\" | etc,\n  imageFilePathOrBufferWithPNGdata,\n  \"1x\" | \"2x\" | \"3x\" | undefined,\n  \"ru\"\n);\n```\n\nLocalization applies for all fields' `label` and `value`. There is a note about that in [documentation](https://developer.apple.com/library/ios/documentation/UserExperience/Conceptual/PassKit_PG/Creating.html).\n\n# Generate the file\n\nTo generate a file:\n\n```js\nconst buf = await pass.asBuffer();\nawait fs.writeFile(\"pathToPass.pkpass\", buf);\n```\n\nYou can send the buffer directly to an HTTP server response:\n\n```js\napp.use(async (ctx, next) =\u003e {\n  ctx.status = 200;\n  ctx.type = passkit.constants.PASS_MIME_TYPE;\n  ctx.body = await pass.asBuffer();\n});\n```\n\n# Troubleshooting with Console app\n\nIf 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.\n\n## Stay in touch\n\n* Author - [Konstantin Vyatkin](https://github.com/tinovyatkin)\n* Email - tino [at] vtkn.io\n\n## License\n\n`@walletpass/pass-js` is [MIT licensed](LICENSE).\n\n# Financial Contributors\n\nBecome a financial contributor and help us sustain our community. [[Contribute](https://opencollective.com/walletpass/contribute)]\n\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftinovyatkin%2Fpass-js","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ftinovyatkin%2Fpass-js","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftinovyatkin%2Fpass-js/lists"}