@astratra/wallet 1.1.0 → 1.2.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/README.md CHANGED
@@ -1,7 +1,7 @@
1
1
  # @astratra/wallet
2
2
 
3
- Des cartes de fidélité dans **Apple Wallet** et **Google Wallet**, qui se
4
- mettent à jour toutes seules. Le client n'installe rien et ne crée aucun
3
+ Des cartes de fidélité, des billets et des cartes d'embarquement dans
4
+ **Apple Wallet** et **Google Wallet**, qui se mettent à jour tout seuls. Le client n'installe rien et ne crée aucun
5
5
  compte : il touche « Ajouter », la carte vit dans son téléphone, et ton serveur
6
6
  la tient à jour.
7
7
 
@@ -14,7 +14,11 @@ le contenu vient de toi.
14
14
  - **La signature Apple** : `.pkpass` signé avec ton certificat Pass Type ID.
15
15
  L'identifiant de carte et l'équipe sont **lus dans le certificat**, et le
16
16
  certificat intermédiaire WWDR G4 d'Apple est fourni : deux champs à saisir au
17
- lieu de cinq.
17
+ lieu de cinq. Le paquet fabrique la carte lui-même (`pass.json`, manifeste,
18
+ signature CMS, archive) avec le seul module `crypto` de Node : aucune
19
+ dépendance tierce à surveiller.
20
+ - **Les cartes qu'Apple refuserait sans rien dire** : refusées dès la
21
+ fabrication, avec un message qui dit quoi corriger (voir plus bas).
18
22
  - **Les mises à jour Apple** : le service web du protocole Apple (inscription
19
23
  des appareils, cartes changées, dernière version, désinscription) et la
20
24
  notification push vide qui déclenche le rafraîchissement. Les jetons morts
@@ -53,6 +57,35 @@ const pkpass = passes.build({
53
57
  });
54
58
  ```
55
59
 
60
+ Sans `webServiceURL`, la carte est **fixe** : Apple ne viendra jamais la
61
+ mettre à jour, et `authenticationToken` n'est pas écrit (une carte de visite,
62
+ par exemple). Avec un `webServiceURL`, le jeton est obligatoire.
63
+
64
+ Avant de signer, `build` refuse (avec une `TypeError` qui dit quoi corriger)
65
+ ce qu'Apple Wallet refuserait sans explication :
66
+
67
+ - deux champs avec la même clé (`key`), recto et dos confondus ;
68
+ - une carte sans `icon.png` (commune ou propre à la carte) ;
69
+ - un jeton de moins de 16 caractères quand il y a un service web ;
70
+ - une couleur qui n'est pas au format `rgb(r, g, b)` ;
71
+ - deux champs avec la même clé dans la zone d'informations
72
+ (`additionalInfoFields`), comptée avec les autres ;
73
+ - un format de code-barres inconnu, ou un format d'iOS 27 (Code 39, Codabar,
74
+ EAN-13, ITF) sans un code `PKBarcodeFormatQR`, `PKBarcodeFormatPDF417`,
75
+ `PKBarcodeFormatAztec` ou `PKBarcodeFormatCode128` après lui : les autres
76
+ téléphones n'afficheraient aucun code ;
77
+ - une date sans heure ou sans fuseau, une plage de dates à l'envers, plus de
78
+ dix lieux, une latitude impossible, une clé mal écrite dans un lieu ou une
79
+ plage (`lat` au lieu de `latitude`) ;
80
+ - un lien du guide de l'événement qui n'est pas en `http(s)` ;
81
+ - une carte d'embarquement sans `transitType`, ou un `transitType` sur une
82
+ autre carte ;
83
+ - un nom d'image qui sort de la carte (`..`, chemin absolu) ou qui prend la
84
+ place d'un fichier fabriqué (`pass.json`, `manifest.json`, `signature`).
85
+
86
+ Une clé privée qui ne correspond pas au certificat, ou une phrase secrète
87
+ fausse, est refusée dès `createApplePasses`, et non à la première carte.
88
+
56
89
  Le service web, monté sous le `webServiceURL` :
57
90
 
58
91
  ```js
@@ -73,6 +106,67 @@ Après chaque changement (visite validée, récompense accordée…), mets à jo
73
106
  await notifyApplePass({ registrations, passTypeIdentifier, serialNumber, certificate, privateKey });
74
107
  ```
75
108
 
109
+ ## Billets, embarquement et cartes riches
110
+
111
+ Tout ce que le format d'Apple prévoit se donne à la fabrique (valable pour
112
+ toutes ses cartes) ou à chaque carte (qui le remplace). Les dates acceptent un
113
+ `Date` ou un texte ISO 8601 avec l'heure et le fuseau.
114
+
115
+ ```js
116
+ const billets = createApplePasses({
117
+ certificate, privateKey, webServiceURL,
118
+ organizationName: 'Théâtre du Port',
119
+ description: 'Billet',
120
+ type: 'eventTicket',
121
+ images: { 'icon.png': icon, 'logo.png': logo, 'background.png': fond, 'thumbnail.png': affiche },
122
+ locations: [{ latitude: 43.2965, longitude: 5.3698, relevantText: 'Vous arrivez au théâtre' }],
123
+ sharingProhibited: true
124
+ });
125
+
126
+ const pkpass = billets.build({
127
+ serialNumber: 'B-2026-0042-1',
128
+ authenticationToken: billet.jeton,
129
+ description: 'Billet pour Le Cid', // remplace celle de la fabrique
130
+ primaryFields: [{ key: 'spectacle', label: 'SPECTACLE', value: 'Le Cid' }],
131
+ secondaryFields: [{ key: 'place', label: 'PLACE', value: 'Orchestre, rang F, 12' }],
132
+ auxiliaryFields: [{ key: 'date', label: 'DATE', value: seance.debut, dateStyle: 'PKDateStyleMedium', timeStyle: 'PKDateStyleShort' }],
133
+ additionalInfoFields: [{ key: 'portes', label: 'OUVERTURE DES PORTES', value: '19 h' }],
134
+ relevantDates: [{ startDate: seance.ouverture, endDate: seance.fin }], // la carte remonte sur l'écran verrouillé
135
+ groupingIdentifier: 'commande-2026-0042', // les billets d'une commande, rangés ensemble
136
+ semantics: { eventName: 'Le Cid', venueName: 'Théâtre du Port', venueRegionName: 'Marseille',
137
+ venueRoom: 'Grande salle', performerNames: ['Troupe du Port'], eventStartDate: seance.debut },
138
+ preferredStyleSchemes: ['posterEventTicket', 'eventTicket'], // billet en affiche (iOS 26)
139
+ barcode: { message: billet.code, format: 'PKBarcodeFormatAztec' }
140
+ });
141
+ ```
142
+
143
+ - **La zone d'informations** (`additionalInfoFields`, iOS 18) s'affiche sous
144
+ la carte. Elle n'est écrite que si elle est remplie.
145
+ - **Le billet en affiche** d'iOS 26 demande `preferredStyleSchemes` et les
146
+ étiquettes sémantiques `eventName`, `venueName`, `venueRegionName` et
147
+ `venueRoom` (et `performerNames` pour un concert, les abréviations des
148
+ équipes pour un match). Sans elles, Apple affiche le billet classique :
149
+ garde donc aussi les champs habituels.
150
+ - **Plusieurs codes** : `barcodes: [...]` à la place de `barcode` ; l'appareil
151
+ affiche le premier qu'il sait lire.
152
+ - **Les liens du guide de l'événement** (`directionsInformationURL`,
153
+ `parkingInformationURL`, `orderFoodURL`, `sellURL`, `transferURL`…) et les
154
+ contacts (`contactVenuePhoneNumber`…) se donnent comme les autres clés.
155
+ - **Une carte d'embarquement** (train, bus, avion, bateau) :
156
+ `type: 'boardingPass'` et `transitType: 'PKTransitTypeTrain'`.
157
+ - **La carte en affiche d'iOS 27** (fidélité, adhésion…) : `posterGeneric`,
158
+ avec ses zones (`headerFields`, `primaryFields`, `footerFields`,
159
+ `backFields`, `additionalInfoFields`), écrite à côté du style classique que
160
+ gardent les appareils plus anciens.
161
+ - **Une clé qu'Apple ajoutera après cette version** : `extraKeys`, écrite telle
162
+ quelle dans le `pass.json`, sans attendre une mise à jour du paquet. Elle ne
163
+ peut pas remplacer une clé que le paquet écrit ou contrôle.
164
+
165
+ La liste complète des clés prises en charge est dans `src/index.d.ts`
166
+ (`ApplePassKeys`). Côté Google, `createGoogleWallet({ kind: 'eventTicket' })`
167
+ (ou `flight`, `transit`) crée des billets ; leur contenu suit l'API de Google
168
+ Wallet, comme pour la fidélité.
169
+
76
170
  ## Google Wallet
77
171
 
78
172
  ```js
@@ -152,15 +246,3 @@ redémarrage.
152
246
  - **Badges** : dans un e-mail ou une page, utilise les badges officiels
153
247
  (« Ajouter à l'app Cartes Apple », « Ajouter au Google Wallet »), téléchargés
154
248
  depuis les kits de marque d'Apple et de Google.
155
- - **Fixe `joi` dans ton projet** : `passkit-generator` 3.7.0 (dernière version)
156
- épingle exactement `joi` 17.13.4. Toutes les versions jusqu'à 17.13.8 ont
157
- des failles connues (pollution de prototype, expression régulière lente) ;
158
- 17.13.9 les corrige. npm n'applique que les `overrides` du projet racine,
159
- pas ceux d'un paquet installé : ajoute-les dans le `package.json` de ton
160
- application. Avec cette surcharge, `npm audit` ne signale plus rien et
161
- `@astratra/wallet` fonctionne normalement. Elle devient inutile dès que
162
- `passkit-generator` met `joi` à jour de lui-même.
163
-
164
- ```json
165
- { "overrides": { "passkit-generator": { "joi": "17.13.9" } } }
166
- ```
package/package.json CHANGED
@@ -1,7 +1,7 @@
1
1
  {
2
2
  "name": "@astratra/wallet",
3
- "version": "1.1.0",
4
- "description": "Apple Wallet and Google Wallet loyalty cards: signed passes, live updates, add-to-wallet links.",
3
+ "version": "1.2.0",
4
+ "description": "Apple Wallet and Google Wallet loyalty cards, event tickets and boarding passes: signed passes, live updates, add-to-wallet links.",
5
5
  "engines": {
6
6
  "node": ">=22"
7
7
  },
@@ -25,7 +25,9 @@
25
25
  "apple-wallet",
26
26
  "google-wallet",
27
27
  "pkpass",
28
- "loyalty"
28
+ "loyalty",
29
+ "event-ticket",
30
+ "boarding-pass"
29
31
  ],
30
32
  "license": "MIT",
31
33
  "publishConfig": {
@@ -34,8 +36,7 @@
34
36
  "dependencies": {
35
37
  "@astratra/core": "^1.1.0",
36
38
  "express": "^4.18.3 || ^5.0.0",
37
- "google-auth-library": "^11.1.0",
38
- "passkit-generator": "^3.6.1"
39
+ "google-auth-library": "^11.1.0"
39
40
  },
40
41
  "devDependencies": {
41
42
  "jest": "30.4.2",
package/src/apple.js CHANGED
@@ -1,9 +1,37 @@
1
1
  const http2 = require('node:http2');
2
- const { PKPass } = require('passkit-generator');
3
2
  const { APPLE_WWDR_G4, readPassCertificate } = require('./credentials');
3
+ const { fabriquerPkpass, preparerSignataire } = require('./pkpass/pkpass');
4
+ const { NOMS_OPTIONS } = require('./pkpass/options');
4
5
 
5
6
  const APNS_PRODUCTION = 'https://api.push.apple.com';
6
7
 
8
+ /* Un QR code quand le format n'est pas dit ; ce qui n'est pas un objet est
9
+ laissé tel quel, pour être refusé avec un message clair. */
10
+ function avecFormatParDefaut(code) {
11
+ return code && typeof code === 'object' ? { ...code, format: code.format || 'PKBarcodeFormatQR' } : code;
12
+ }
13
+
14
+ /* Les clés de premier niveau (dates, lieux, billets groupés…) données à la
15
+ fabrique valent pour toutes ses cartes ; une carte les remplace une à une. */
16
+ function optionsDe(source) {
17
+ const options = {};
18
+ for (const nom of NOMS_OPTIONS) {
19
+ if (source[nom] !== undefined && source[nom] !== null) options[nom] = source[nom];
20
+ }
21
+ return options;
22
+ }
23
+
24
+ /* Les extraKeys de la carte s'ajoutent à ceux de la fabrique ; ce qui n'est
25
+ pas un objet passe tel quel, pour être refusé avec un message clair. */
26
+ function fusionnerExtra(communs, propres) {
27
+ if (communs === undefined || communs === null) return propres;
28
+ if (propres === undefined || propres === null) return communs;
29
+ const objet = (valeur) => typeof valeur === 'object' && !Array.isArray(valeur);
30
+ if (!objet(communs)) return communs;
31
+ if (!objet(propres)) return propres;
32
+ return { ...communs, ...propres };
33
+ }
34
+
7
35
  /**
8
36
  * Fabrique de cartes Apple Wallet (storeCard par défaut), signées avec le
9
37
  * certificat Pass Type ID de l'émetteur.
@@ -12,34 +40,59 @@ const APNS_PRODUCTION = 'https://api.push.apple.com';
12
40
  * (couleurs, logo) est celui de l'émetteur ; le contenu (champs, bande, QR)
13
41
  * change d'une carte à l'autre.
14
42
  *
43
+ * Le .pkpass est fabriqué par le paquet lui-même (pass.json, manifest,
44
+ * signature CMS, ZIP), sans autre dépendance que Node.
45
+ *
15
46
  * @param {object} options
16
47
  * @param {string} options.certificate certificat Pass Type ID (PEM).
17
48
  * @param {string} options.privateKey clé privée associée (PEM).
18
49
  * @param {string} [options.passphrase]
19
50
  * @param {string} [options.wwdr] certificat intermédiaire ; WWDR G4 par défaut.
20
- * @param {string} options.webServiceURL base du service web de mise à jour (…/v1 ajouté par Apple).
51
+ * @param {string} [options.webServiceURL] base du service web de mise à jour (…/v1 ajouté par Apple) ;
52
+ * sans elle, la carte est fixe.
21
53
  * @param {string} options.organizationName
22
54
  * @param {string} options.description
23
- * @param {Record<string, Buffer>} options.images images communes : icon.png, icon@2x.png, logo.png…
24
- * @param {{foregroundColor?: string, backgroundColor?: string, labelColor?: string}} [options.colors]
25
- * @param {'storeCard'|'generic'|'coupon'|'eventTicket'} [options.type='storeCard']
55
+ * @param {Record<string, Buffer>} options.images images communes : icon.png (obligatoire), icon@2x.png, logo.png…
56
+ * @param {{foregroundColor?: string, backgroundColor?: string, labelColor?: string}} [options.colors] au format rgb(r, g, b).
57
+ * @param {'storeCard'|'generic'|'coupon'|'eventTicket'|'boardingPass'} [options.type='storeCard']
58
+ * @param {string} [options.transitType] carte d'embarquement : PKTransitTypeAir, Boat, Bus, Generic ou Train.
59
+ * @param {string} [options.logoText]
60
+ * @param {Record<string, unknown>} [options.extraKeys] autres clés du pass.json, écrites telles quelles
61
+ * (une clé qu'Apple ajoute après cette version du paquet).
62
+ * Toutes les clés de premier niveau d'Apple prises en charge (relevantDates,
63
+ * locations, semantics, groupingIdentifier… voir index.d.ts) se donnent ici
64
+ * pour toutes les cartes, ou dans chaque carte.
26
65
  */
27
66
  function createApplePasses({
28
- certificate, privateKey, passphrase, wwdr = APPLE_WWDR_G4, webServiceURL,
29
- organizationName, description, images = {}, colors = {}, type = 'storeCard', logoText
67
+ certificate, privateKey, passphrase, wwdr, webServiceURL,
68
+ organizationName, description, images = {}, colors = {}, type = 'storeCard', logoText,
69
+ transitType, extraKeys, ...reglages
30
70
  }) {
31
71
  const lu = readPassCertificate(certificate);
32
72
  if (!lu?.passTypeIdentifier || !lu.teamIdentifier) {
33
73
  throw new Error('Certificat Pass Type ID illisible ou incomplet.');
34
74
  }
35
75
  const { passTypeIdentifier, teamIdentifier } = lu;
76
+ /* Absent, null ou vide (un champ de réglage laissé blanc) : celui d'Apple. */
77
+ const signataire = preparerSignataire({ certificate, privateKey, passphrase, wwdr: wwdr || APPLE_WWDR_G4 });
78
+ const optionsCommunes = optionsDe(reglages);
36
79
 
37
80
  /**
38
81
  * @param {object} card
39
82
  * @param {string} card.serialNumber
40
- * @param {string} card.authenticationToken au moins 16 caractères (exigence Apple).
41
- * @param {Array<object>} [card.headerFields] … et primaryFields, secondaryFields, auxiliaryFields, backFields
83
+ * @param {string} [card.authenticationToken] au moins 16 caractères (exigence Apple) ;
84
+ * obligatoire avec un webServiceURL, ignoré sans.
85
+ * @param {Array<object>} [card.headerFields] … et primaryFields, secondaryFields, auxiliaryFields, backFields,
86
+ * additionalInfoFields ; chaque clé (key) est unique sur toute la carte.
42
87
  * @param {{message: string, altText?: string, format?: string}} [card.barcode]
88
+ * @param {Array<{message: string, altText?: string, format?: string}>} [card.barcodes] plusieurs codes,
89
+ * le premier lisible par l'appareil étant affiché (à la place de barcode).
90
+ * @param {object} [card.posterGeneric] zones de la carte en affiche (iOS 27).
91
+ * @param {string} [card.description] remplace celle de la fabrique (« Billet pour… »).
92
+ * @param {string} [card.logoText] remplace celui de la fabrique.
93
+ * @param {object} [card.colors] remplacent celles de la fabrique, une à une.
94
+ * @param {string} [card.transitType] remplace celui de la fabrique.
95
+ * @param {Record<string, unknown>} [card.extraKeys] s'ajoutent à ceux de la fabrique.
43
96
  * @param {Record<string, Buffer>} [card.images] images propres à cette carte (strip.png…), prioritaires.
44
97
  * @param {boolean} [card.voided] carte annulée : Apple Wallet la grise et la
45
98
  * déclare inutilisable. C'est la seule façon, côté émetteur, de
@@ -47,36 +100,33 @@ function createApplePasses({
47
100
  * @returns {Buffer} le .pkpass
48
101
  */
49
102
  function build(card) {
50
- const pass = new PKPass(
51
- { ...images, ...(card.images || {}) },
52
- { wwdr, signerCert: certificate, signerKey: privateKey, signerKeyPassphrase: passphrase },
53
- {
54
- formatVersion: 1,
103
+ return fabriquerPkpass({
104
+ pass: {
105
+ type,
55
106
  passTypeIdentifier,
56
107
  teamIdentifier,
57
108
  serialNumber: card.serialNumber,
58
109
  organizationName,
59
- description,
60
- ...(logoText ? { logoText } : {}),
61
- ...colors,
110
+ description: card.description ?? description,
111
+ /* Un logoText vide n'est pas écrit, comme avant. */
112
+ logoText: (card.logoText ?? logoText) || undefined,
113
+ colors: { ...(colors || {}), ...(card.colors || {}) },
62
114
  webServiceURL,
63
115
  authenticationToken: card.authenticationToken,
64
- ...(card.voided ? { voided: true } : {})
65
- }
66
- );
67
- pass.type = type;
68
- for (const zone of ['headerFields', 'primaryFields', 'secondaryFields', 'auxiliaryFields', 'backFields']) {
69
- for (const field of card[zone] || []) pass[zone].push(field);
70
- }
71
- if (card.barcode) {
72
- pass.setBarcodes({
73
- format: card.barcode.format || 'PKBarcodeFormatQR',
74
- message: card.barcode.message,
75
- messageEncoding: 'utf-8',
76
- ...(card.barcode.altText ? { altText: card.barcode.altText } : {})
77
- });
78
- }
79
- return pass.getAsBuffer();
116
+ voided: Boolean(card.voided),
117
+ transitType: card.transitType ?? transitType,
118
+ fields: card,
119
+ ...(card.posterGeneric ? { posterGeneric: card.posterGeneric } : {}),
120
+ ...(card.barcode ? { barcode: avecFormatParDefaut(card.barcode) } : {}),
121
+ ...(card.barcodes !== undefined
122
+ ? { barcodes: Array.isArray(card.barcodes) ? card.barcodes.map(avecFormatParDefaut) : card.barcodes }
123
+ : {}),
124
+ options: { ...optionsCommunes, ...optionsDe(card) },
125
+ extraKeys: fusionnerExtra(extraKeys, card.extraKeys)
126
+ },
127
+ fichiers: { ...images, ...(card.images || {}) },
128
+ signataire
129
+ });
80
130
  }
81
131
 
82
132
  return { passTypeIdentifier, teamIdentifier, expiresAt: lu.expiresAt, build };
package/src/google.js CHANGED
@@ -6,12 +6,16 @@ const SCOPE = 'https://www.googleapis.com/auth/wallet_object.issuer';
6
6
 
7
7
  /* Chaque type de carte Google a sa ressource REST et sa clé dans le JWT
8
8
  d'ajout. La fidélité est le cas courant ; les autres suivent le même
9
- chemin. */
9
+ chemin : billets d'événement, cartes d'embarquement (vols) et titres de
10
+ transport. */
10
11
  const KINDS = {
11
12
  loyalty: { resource: 'loyalty', jwtKey: 'loyaltyObjects' },
12
13
  generic: { resource: 'generic', jwtKey: 'genericObjects' },
13
14
  offer: { resource: 'offer', jwtKey: 'offerObjects' },
14
- giftCard: { resource: 'giftCard', jwtKey: 'giftCardObjects' }
15
+ giftCard: { resource: 'giftCard', jwtKey: 'giftCardObjects' },
16
+ eventTicket: { resource: 'eventTicket', jwtKey: 'eventTicketObjects' },
17
+ flight: { resource: 'flight', jwtKey: 'flightObjects' },
18
+ transit: { resource: 'transit', jwtKey: 'transitObjects' }
15
19
  };
16
20
 
17
21
  const base64urlJson = (value) => Buffer.from(JSON.stringify(value)).toString('base64url');
@@ -39,7 +43,7 @@ function signSaveJwt(payload, credentials, { now = new Date(), origins } = {}) {
39
43
  * @param {object} options
40
44
  * @param {string} options.issuerId
41
45
  * @param {object} options.credentials JSON du compte de service (client_email, private_key).
42
- * @param {'loyalty'|'generic'|'offer'|'giftCard'} [options.kind='loyalty']
46
+ * @param {'loyalty'|'generic'|'offer'|'giftCard'|'eventTicket'|'flight'|'transit'} [options.kind='loyalty']
43
47
  * @param {(options: object) => Promise<object>} [options.request] remplace le client HTTP (tests).
44
48
  */
45
49
  function createGoogleWallet({ issuerId, credentials, kind = 'loyalty', request }) {
package/src/index.d.ts CHANGED
@@ -30,38 +30,154 @@ export function fromHexField(value: string | undefined): string | undefined;
30
30
  export interface PassField {
31
31
  key: string;
32
32
  label?: string;
33
- value: string | number;
33
+ /** A Date is written as ISO 8601 text; use dateStyle / timeStyle to show it as a date. */
34
+ value: string | number | Date;
35
+ attributedValue?: string | number | Date;
34
36
  textAlignment?: string;
35
37
  changeMessage?: string;
38
+ dateStyle?: 'PKDateStyleNone' | 'PKDateStyleShort' | 'PKDateStyleMedium' | 'PKDateStyleLong' | 'PKDateStyleFull';
39
+ timeStyle?: 'PKDateStyleNone' | 'PKDateStyleShort' | 'PKDateStyleMedium' | 'PKDateStyleLong' | 'PKDateStyleFull';
36
40
  [key: string]: unknown;
37
41
  }
38
42
 
39
- export interface PassContent {
43
+ export type BarcodeFormat =
44
+ | 'PKBarcodeFormatQR' | 'PKBarcodeFormatPDF417' | 'PKBarcodeFormatAztec' | 'PKBarcodeFormatCode128'
45
+ /** iOS 27 and later: follow with one of the four formats above for older devices. */
46
+ | 'PKBarcodeFormatCode39' | 'PKBarcodeFormatCodabar' | 'PKBarcodeFormatEAN13' | 'PKBarcodeFormatI2of5';
47
+
48
+ export interface PassBarcode {
49
+ message: string;
50
+ altText?: string;
51
+ /** QR code unless another format is given. */
52
+ format?: BarcodeFormat;
53
+ /** utf-8 unless another character set is given (iso-8859-1…). */
54
+ messageEncoding?: string;
55
+ }
56
+
57
+ export type TransitType = 'PKTransitTypeAir' | 'PKTransitTypeBoat' | 'PKTransitTypeBus' | 'PKTransitTypeGeneric' | 'PKTransitTypeTrain';
58
+
59
+ /** ISO 8601 text with time and time zone (2026-12-31T20:30+01:00), or a Date. */
60
+ export type PassDate = string | Date;
61
+
62
+ /**
63
+ * Top-level Apple keys (WalletPasses › Pass), checked then written as is.
64
+ * Given to createApplePasses, they apply to every card; a card replaces them one by one.
65
+ */
66
+ export interface ApplePassKeys {
67
+ /** When the card shows on the lock screen: one date, or a start and an end (iOS 18). */
68
+ relevantDates?: Array<{ date: PassDate } | { startDate: PassDate; endDate: PassDate }>;
69
+ /** Older devices (before iOS 18). */
70
+ relevantDate?: PassDate;
71
+ expirationDate?: PassDate;
72
+ /** Up to 10 places where the card shows on the lock screen. */
73
+ locations?: Array<{ latitude: number; longitude: number; altitude?: number; relevantText?: string }>;
74
+ /** Metres. */
75
+ maxDistance?: number;
76
+ beacons?: Array<{ proximityUUID: string; major?: number; minor?: number; relevantText?: string }>;
77
+ /** Tickets of one order shown as a group (event tickets and boarding passes). */
78
+ groupingIdentifier?: string;
79
+ sharingProhibited?: boolean;
80
+ suppressStripShine?: boolean;
81
+ /** Apple semantic tags (eventName, venueName, seats…); Dates become ISO 8601 text. */
82
+ semantics?: Record<string, unknown>;
83
+ /** Hidden data for a companion app. */
84
+ userInfo?: Record<string, unknown>;
85
+ /** For example ['posterEventTicket', 'eventTicket']. */
86
+ preferredStyleSchemes?: string[];
87
+ eventLogoText?: string;
88
+ footerBackgroundColor?: string;
89
+ useAutomaticColors?: boolean;
90
+ suppressHeaderDarkening?: boolean;
91
+ contactVenueEmail?: string;
92
+ contactVenuePhoneNumber?: string;
93
+ transitProviderEmail?: string;
94
+ transitProviderPhoneNumber?: string;
95
+ associatedStoreIdentifiers?: number[];
96
+ auxiliaryStoreIdentifiers?: number[];
97
+ /** Passed to the associated app; a custom scheme is allowed. */
98
+ appLaunchURL?: string;
99
+ nfc?: { message: string; encryptionPublicKey: string; requiresAuthentication?: boolean };
100
+ accessibilityURL?: string;
101
+ addOnURL?: string;
102
+ bagPolicyURL?: string;
103
+ contactVenueWebsite?: string;
104
+ directionsInformationURL?: string;
105
+ merchandiseURL?: string;
106
+ orderFoodURL?: string;
107
+ parkingInformationURL?: string;
108
+ purchaseParkingURL?: string;
109
+ sellURL?: string;
110
+ transferURL?: string;
111
+ transitInformationURL?: string;
112
+ changeSeatURL?: string;
113
+ entertainmentURL?: string;
114
+ managementURL?: string;
115
+ purchaseAdditionalBaggageURL?: string;
116
+ purchaseLoungeAccessURL?: string;
117
+ purchaseWifiURL?: string;
118
+ registerServiceAnimalURL?: string;
119
+ reportLostBagURL?: string;
120
+ requestWheelchairURL?: string;
121
+ trackBagsURL?: string;
122
+ transitProviderWebsiteURL?: string;
123
+ upgradeURL?: string;
124
+ /**
125
+ * Any other pass.json key, written as is (one Apple adds after this version).
126
+ * Cannot replace a key the package writes, nor a key listed above.
127
+ */
128
+ extraKeys?: Record<string, unknown>;
129
+ }
130
+
131
+ export interface PosterGenericFields {
132
+ headerFields?: PassField[];
133
+ primaryFields?: PassField[];
134
+ footerFields?: PassField[];
135
+ backFields?: PassField[];
136
+ additionalInfoFields?: PassField[];
137
+ }
138
+
139
+ export interface PassContent extends ApplePassKeys {
40
140
  serialNumber: string;
41
- /** At least 16 characters (Apple requirement). */
42
- authenticationToken: string;
141
+ /** At least 16 characters (Apple requirement). Required with a webServiceURL; not written without one. */
142
+ authenticationToken?: string;
43
143
  headerFields?: PassField[];
44
144
  primaryFields?: PassField[];
45
145
  secondaryFields?: PassField[];
46
146
  auxiliaryFields?: PassField[];
47
147
  backFields?: PassField[];
48
- barcode?: { message: string; altText?: string; format?: string };
148
+ /** Additional Info section below the card (iOS 18); written only when filled. */
149
+ additionalInfoFields?: PassField[];
150
+ barcode?: PassBarcode;
151
+ /** Several codes, the first one the device can show is shown (instead of barcode). */
152
+ barcodes?: PassBarcode[];
153
+ /** Poster layout (iOS 27), written next to the classic style that older devices keep. Not for boarding passes. */
154
+ posterGeneric?: PosterGenericFields;
155
+ /** Replace the issuer's values for this card. */
156
+ description?: string;
157
+ logoText?: string;
158
+ colors?: { foregroundColor?: string; backgroundColor?: string; labelColor?: string };
159
+ transitType?: TransitType;
49
160
  images?: Record<string, Buffer>;
50
161
  /** Voided card: Apple Wallet greys it out. The only way for an issuer to retire a card already added. */
51
162
  voided?: boolean;
52
163
  }
53
164
 
54
- export interface ApplePassesOptions {
165
+ export interface ApplePassesOptions extends ApplePassKeys {
55
166
  certificate: string;
56
167
  privateKey: string;
57
168
  passphrase?: string;
58
169
  wwdr?: string;
59
- webServiceURL: string;
170
+ /** Base of the update web service (Apple adds /v1). Without it, the card is fixed: never updated. */
171
+ webServiceURL?: string;
60
172
  organizationName: string;
61
173
  description: string;
174
+ /** Shared images; icon.png is required (here or in each card's images). */
62
175
  images?: Record<string, Buffer>;
176
+ /** Each colour as rgb(r, g, b). */
63
177
  colors?: { foregroundColor?: string; backgroundColor?: string; labelColor?: string };
64
- type?: 'storeCard' | 'generic' | 'coupon' | 'eventTicket';
178
+ type?: 'storeCard' | 'generic' | 'coupon' | 'eventTicket' | 'boardingPass';
179
+ /** Required for a boarding pass. */
180
+ transitType?: TransitType;
65
181
  logoText?: string;
66
182
  }
67
183
 
@@ -119,7 +235,7 @@ export function createAppleWebServiceRouter(options: {
119
235
  logger?: { warn(message: string): void };
120
236
  }): Router;
121
237
 
122
- export type GoogleKind = 'loyalty' | 'generic' | 'offer' | 'giftCard';
238
+ export type GoogleKind = 'loyalty' | 'generic' | 'offer' | 'giftCard' | 'eventTicket' | 'flight' | 'transit';
123
239
 
124
240
  export interface GoogleWallet {
125
241
  classId(suffix: string): string;