Add semantic tags support

Author: molang163

README.md

@@ -192,6 +192,30 @@ pass.primaryFields.delete("date");
 pass.primaryFields.clear();
 ```
 
+You can add Apple Wallet semantic tags at the pass level or on a specific
+field:
+
+```js
+pass.semantics = {
+  eventName: "Animated Movie",
+  venueName: "Steve Jobs Theater",
+  venueLocation: {
+    latitude: 37.330886,
+    longitude: -122.007427
+  }
+};
+
+pass.secondaryFields.add({
+  key: "runtime",
+  label: "Run Time",
+  value: "1:21",
+  semantics: {
+    eventStartDate: new Date("2025-01-02T19:00:00-08:00"),
+    eventEndDate: "2025-01-02T20:21-08:00"
+  }
+});
+```
+
 Adding images to a pass is the same as adding images to a template (see above).
 
 # Working with Dates
@@ -295,4 +319,3 @@ If the pass file generates without errors but you aren't able to open your pass
 # Financial Contributors
 
 Become a financial contributor and help us sustain our community. [[Contribute](https://opencollective.com/walletpass/contribute)]
-

__tests__/base-pass.ts

@@ -1,5 +1,6 @@
 import { PassBase } from '../src/lib/base-pass';
 import { TOP_LEVEL_FIELDS } from '../src/constants';
+import { getW3CDateString } from '../src/lib/w3cdate';
 import 'jest-extended';
 
 describe('PassBase', () => {
@@ -40,6 +41,41 @@ describe('PassBase', () => {
     }).toThrow(TypeError);
   });
 
+  it('works with semantic tags', () => {
+    const eventStartDate = new Date(2025, 0, 2, 3, 4);
+    const bp = new PassBase({
+      eventTicket: {},
+      semantics: {
+        eventName: 'Animated Movie',
+        eventStartDate,
+        totalPrice: {
+          amount: 1250,
+          currencyCode: 'USD',
+        },
+        venueLocation: {
+          latitude: 37.330886,
+          longitude: -122.007427,
+        },
+      },
+    });
+
+    expect(bp.semantics).toEqual({
+      eventName: 'Animated Movie',
+      eventStartDate: getW3CDateString(eventStartDate),
+      totalPrice: {
+        amount: 1250,
+        currencyCode: 'USD',
+      },
+      venueLocation: {
+        latitude: 37.330886,
+        longitude: -122.007427,
+      },
+    });
+    expect(JSON.stringify(bp)).toContain('"semantics"');
+    bp.semantics = undefined;
+    expect(bp.semantics).toBeUndefined();
+  });
+
   it('webServiceURL', () => {
     const bp = new PassBase();
     expect(() => {

__tests__/fieldsMap.ts

@@ -41,3 +41,28 @@ test('FieldsMap Class', () => {
     )}"}]`,
   );
 });
+
+test('FieldsMap serializes semantic tags', () => {
+  const fields = new FieldsMap();
+  const eventStartDate = new Date(2025, 0, 2, 3, 4);
+
+  fields.add({
+    key: 'event',
+    label: 'Venue',
+    value: 'Steve Jobs Theater',
+    semantics: {
+      eventName: 'Animated Movie',
+      eventStartDate,
+      venueLocation: {
+        latitude: 37.330886,
+        longitude: -122.007427,
+      },
+    },
+  });
+
+  expect(JSON.stringify(fields)).toBe(
+    `[{"key":"event","label":"Venue","value":"Steve Jobs Theater","semantics":{"eventName":"Animated Movie","eventStartDate":"${getW3CDateString(
+      eventStartDate,
+    )}","venueLocation":{"latitude":37.330886,"longitude":-122.007427}}}]`,
+  );
+});

src/constants.ts

@@ -204,6 +204,9 @@ export const TOP_LEVEL_FIELDS: {
     templatable: true,
     localizable: true,
   },
+  semantics: {
+    type: Object,
+  },
   suppressStripShine: {
     type: Boolean,
     templatable: true,

src/index.ts

@@ -3,3 +3,4 @@ import * as constants from './constants';
 export { constants };
 export { Template } from './template';
 export { Pass } from './pass';
+export type { SemanticTags, SemanticTagValue } from './interfaces';

src/interfaces.ts

@@ -32,12 +32,34 @@ export type NumberStyle =
   | 'PKNumberStyleScientific'
   | 'PKNumberStyleSpellOut';
 
+export interface SemanticTagObject {
+  [key: string]: SemanticTagValue;
+}
+
+export type SemanticTagValue =
+  | string
+  | number
+  | boolean
+  | Date
+  | SemanticTagObject
+  | SemanticTagValue[];
+
+/**
+ * Machine-readable metadata that Wallet uses to offer a pass and suggest
+ * related actions.
+ *
+ * @see {@link https://developer.apple.com/documentation/walletpasses/supporting-semantic-tags-in-wallet-passes}
+ * @see {@link https://developer.apple.com/documentation/walletpasses/semantictags}
+ */
+export type SemanticTags = SemanticTagObject;
+
 export type FieldDescriptor = {
   // Standard Field Dictionary Keys
   label?: string;
   attributedValue?: string | number;
   changeMessage?: string;
   dataDetectorTypes?: DataDetectors[];
+  semantics?: SemanticTags;
 } & (
   | {
       value: string;
@@ -176,6 +198,14 @@ export interface PassCompanionAppKeys {
   userInfo?: any; // eslint-disable-line @typescript-eslint/no-explicit-any
 }
 
+export interface PassSemanticKeys {
+  /**
+   * Machine-readable metadata for Wallet suggestions. This dictionary may also
+   * be specified on individual pass fields.
+   */
+  semantics?: SemanticTags;
+}
+
 /**
  * Information about when a pass expires and whether it is still valid.
  * A pass is marked as expired if the current date is after the pass’s expiration date,
@@ -442,6 +472,7 @@ export type PassStructureFields =
 export type ApplePass = PassStandardKeys &
   PassAssociatedAppKeys &
   PassCompanionAppKeys &
+  PassSemanticKeys &
   PassExpirationKeys &
   PassRelevanceKeys &
   PassVisualAppearanceKeys &
@@ -450,4 +481,4 @@ export type ApplePass = PassStandardKeys &
 
   export interface Options {
     allowHttp: boolean
-  }
+  }

src/lib/base-pass.ts

@@ -1,11 +1,12 @@
-import { ApplePass, Options } from '../interfaces';
+import { ApplePass, Options, SemanticTags } from '../interfaces';
 import { BARCODES_FORMAT, STRUCTURE_FIELDS } from '../constants';
 
 import { PassColor } from './pass-color';
 import { PassImages } from './images';
 import { Localizations } from './localizations';
 import { getGeoPoint } from './get-geo-point';
 import { PassStructure } from './pass-structure';
+import { normalizeSemanticTags } from './semantic-tags';
 import { getW3CDateString, isValidW3CDateString } from './w3cdate';
 
 const STRUCTURE_FIELDS_SET = new Set([...STRUCTURE_FIELDS, 'nfc']);
@@ -205,6 +206,21 @@ export class PassBase extends PassStructure {
     else this.fields.description = v;
   }
 
+  /**
+   * Machine-readable metadata used by Wallet to offer pass-related actions.
+   */
+  get semantics(): SemanticTags | undefined {
+    return this.fields.semantics;
+  }
+
+  set semantics(v: SemanticTags | undefined) {
+    if (!v) {
+      delete this.fields.semantics;
+      return;
+    }
+    this.fields.semantics = normalizeSemanticTags(v);
+  }
+
   /**
    * Display name of the organization that originated and signed the pass.
    */

src/lib/fieldsMap.ts

@@ -2,6 +2,7 @@
 
 import { Field, FieldDescriptor, DataStyleFormat } from '../interfaces';
 
+import { normalizeSemanticTags } from './semantic-tags';
 import { getW3CDateString } from './w3cdate';
 
 export class FieldsMap extends Map<string, FieldDescriptor> {
@@ -12,10 +13,13 @@ export class FieldsMap extends Map<string, FieldDescriptor> {
     if (!this.size) return undefined;
     return [...this].map(
       ([key, data]): Field => {
+        const field = { key, ...data };
         // Remap Date objects to string
-        if (data.value instanceof Date)
-          data.value = getW3CDateString(data.value);
-        return { key, ...data };
+        if (field.value instanceof Date)
+          field.value = getW3CDateString(field.value);
+        if (field.semantics)
+          field.semantics = normalizeSemanticTags(field.semantics);
+        return field;
       },
     );
   }

src/lib/pass-structure.ts

@@ -7,6 +7,7 @@
 
 import {
   ApplePass,
+  BoardingPass,
   PassStyle,
   TransitType,
   PassCommonStructure,
@@ -97,7 +98,10 @@ export class PassStructure {
       );
 
     if (!v) {
-      if (this.fields.boardingPass) delete this.fields.boardingPass.transitType;
+      if (this.fields.boardingPass)
+        delete (this.fields.boardingPass as Partial<
+          BoardingPass['boardingPass']
+        >).transitType;
     } else {
       if (Object.values(TRANSIT).includes(v)) {
         if (this.fields.boardingPass) this.fields.boardingPass.transitType = v;

src/lib/semantic-tags.ts

@@ -0,0 +1,28 @@
+'use strict';
+
+import type { SemanticTags, SemanticTagValue } from '../interfaces';
+
+import { getW3CDateString } from './w3cdate';
+
+function normalizeSemanticValue(value: SemanticTagValue): SemanticTagValue {
+  if (value instanceof Date) {
+    if (!Number.isFinite(value.getTime()))
+      throw new TypeError(`Semantic tag dates must be valid Date instances`);
+    return getW3CDateString(value);
+  }
+
+  if (Array.isArray(value)) return value.map(normalizeSemanticValue);
+
+  if (value && typeof value === 'object') {
+    const result: { [key: string]: SemanticTagValue } = {};
+    for (const [key, nestedValue] of Object.entries(value))
+      result[key] = normalizeSemanticValue(nestedValue);
+    return result;
+  }
+
+  return value;
+}
+
+export function normalizeSemanticTags(tags: SemanticTags): SemanticTags {
+  return normalizeSemanticValue(tags) as SemanticTags;
+}