@owask/tapace-templates 0.0.0-stage → 0.1.0

package/README.md

@@ -1,3 +1,14 @@
-# Temporary Holding Version
+# @owask/tapace-templates
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+TapAce's template contract and wallet preview compiler. The source lives in
+`tapace-backend/src/templates` (`contract/`, `compiler/`, `public-api.ts`); this
+folder only builds and publishes it, so the dashboard previews a design with the
+same code the API uses to validate and issue passes.
+
+```bash
+npm run templates:build
+npm run templates:publish
+```
+
+Bump `version` here before publishing, then update the dependency in
+`tapace-frontend`.

package/dist/compiler/event-ticket.d.ts

@@ -0,0 +1,38 @@
+import type { GoogleEvent, SemanticTags } from 'passmint';
+import { type EventDetails, type FieldDef, type FieldValue, type TemplateDefinition } from '../contract/index.js';
+type Mode = 'preview' | 'issue';
+type ValueOf = (field: FieldDef) => FieldValue | undefined;
+/** The event detail an event-bound field shows, or undefined when the event lacks it. */
+export declare function eventValue(field: FieldDef, event: EventDetails | undefined): string | undefined;
+/**
+ * Apple formats an event time on the device. `ignoresTimeZone` keeps the venue's
+ * local time, which is what a ticket shows wherever the holder is.
+ */
+export declare function appleDateStyle(field: FieldDef): {
+    ignoresTimeZone: boolean;
+    dateStyle: "medium" | "none";
+    timeStyle: "short" | "none";
+} | undefined;
+/** Event and seat metadata: Apple's semantic tags, and the source of Google's event ticket. */
+export declare function eventSemantics(def: TemplateDefinition, valueOf: ValueOf): SemanticTags | undefined;
+/** The Google-only part of an event ticket. */
+export declare function googleEvent(def: TemplateDefinition, valueOf: ValueOf, holderName: string | undefined): GoogleEvent | undefined;
+/** Within this distance Google's geofence treats a point as the venue itself. */
+export declare const NEAR_VENUE_METRES = 50;
+/**
+ * The pass's Lock Screen locations as Google `merchantLocations`. An event
+ * ticket's venue is already on its Google class, so points at the venue are left
+ * out. Google writes its own notification text, so messages are not sent.
+ */
+export declare function googleLocations(def: TemplateDefinition, locations: readonly {
+    latitude: number;
+    longitude: number;
+}[]): {
+    latitude: number;
+    longitude: number;
+}[];
+/** Google shows the event and the seat natively, so their fields aren't text rows. */
+export declare function googleShowsNatively(def: TemplateDefinition, field: FieldDef): boolean;
+/** An event-bound field's value: the event's, else a preview sample. */
+export declare function eventFieldValue(def: TemplateDefinition, field: FieldDef, mode: Mode): FieldValue | undefined;
+export {};

package/dist/compiler/event-ticket.js

@@ -0,0 +1,131 @@
+import { isEventTime, resolveCardItem, } from '../contract/index.js';
+/** The event detail an event-bound field shows, or undefined when the event lacks it. */
+export function eventValue(field, event) {
+    switch (field.event) {
+        case 'name':
+            return event?.name;
+        case 'venueName':
+            return event?.venue?.name;
+        case 'venueAddress':
+            return event?.venue?.address;
+        case 'doorsOpen':
+        case 'start':
+        case 'end':
+            return event?.[field.event];
+        default:
+            return undefined;
+    }
+}
+const APPLE_STYLES = {
+    dateTime: { dateStyle: 'medium', timeStyle: 'short' },
+    date: { dateStyle: 'medium', timeStyle: 'none' },
+    time: { dateStyle: 'none', timeStyle: 'short' },
+};
+/**
+ * Apple formats an event time on the device. `ignoresTimeZone` keeps the venue's
+ * local time, which is what a ticket shows wherever the holder is.
+ */
+export function appleDateStyle(field) {
+    if (field.binding !== 'event' || !field.event || !isEventTime(field.event))
+        return undefined;
+    return { ...APPLE_STYLES[field.dateFormat ?? 'dateTime'], ignoresTimeZone: true };
+}
+const GOOGLE_DATE_FORMATS = {
+    dateTime: 'DATE_TIME',
+    date: 'DATE_ONLY',
+    time: 'TIME_ONLY',
+};
+function roleField(def, role) {
+    return def.config.fields.find((f) => f.googleRole === role);
+}
+function text(value) {
+    if (value === undefined)
+        return undefined;
+    const out = String(value).trim();
+    return out === '' ? undefined : out;
+}
+/** Event and seat metadata: Apple's semantic tags, and the source of Google's event ticket. */
+export function eventSemantics(def, valueOf) {
+    if (def.type !== 'event_ticket')
+        return undefined;
+    const event = def.event;
+    const role = (r) => {
+        const field = roleField(def, r);
+        return field ? text(valueOf(field)) : undefined;
+    };
+    const seat = {
+        ...(role('seat') ? { seatNumber: role('seat') } : {}),
+        ...(role('row') ? { seatRow: role('row') } : {}),
+        ...(role('section') ? { seatSection: role('section') } : {}),
+    };
+    const tags = {
+        ...(event?.name ? { eventName: event.name } : {}),
+        ...(event?.venue?.name ? { venueName: event.venue.name } : {}),
+        ...(event?.venue?.location ? { venueLocation: event.venue.location } : {}),
+        ...(event?.doorsOpen ? { venueDoorsOpenDate: event.doorsOpen } : {}),
+        ...(event?.start ? { eventStartDate: event.start } : {}),
+        ...(event?.end ? { eventEndDate: event.end } : {}),
+        ...(role('gate') ? { venueEntrance: role('gate') } : {}),
+        ...(Object.keys(seat).length > 0 ? { seats: [seat] } : {}),
+    };
+    return Object.keys(tags).length > 0 ? tags : undefined;
+}
+function cardItem(item) {
+    if (item.kind === 'seat')
+        return { seat: item.role };
+    if (item.kind === 'event')
+        return { event: item.event, format: GOOGLE_DATE_FORMATS[item.format] };
+    return { field: item.field.key };
+}
+/** The Google-only part of an event ticket. */
+export function googleEvent(def, valueOf, holderName) {
+    if (def.type !== 'event_ticket')
+        return undefined;
+    const ticketTypeField = roleField(def, 'ticketType');
+    const ticketType = ticketTypeField ? text(valueOf(ticketTypeField)) : undefined;
+    const cardRows = def.google.cardRows?.map((row) => row.flatMap((ref) => {
+        const item = resolveCardItem(ref, def.config.fields);
+        return item ? [cardItem(item)] : [];
+    }));
+    return {
+        ...(def.event?.venue?.address ? { venueAddress: def.event.venue.address } : {}),
+        ...(def.event?.doorsOpenLabel ? { doorsOpenLabel: def.event.doorsOpenLabel } : {}),
+        ...(text(holderName) ? { ticketHolderName: text(holderName) } : {}),
+        ...(ticketType ? { ticketType } : {}),
+        ...(cardRows?.length ? { cardRows } : {}),
+    };
+}
+/** Within this distance Google's geofence treats a point as the venue itself. */
+export const NEAR_VENUE_METRES = 50;
+function metresBetween(a, b) {
+    const rad = Math.PI / 180;
+    const dLat = (b.latitude - a.latitude) * rad;
+    const dLng = (b.longitude - a.longitude) * rad;
+    const h = Math.sin(dLat / 2) ** 2 +
+        Math.cos(a.latitude * rad) * Math.cos(b.latitude * rad) * Math.sin(dLng / 2) ** 2;
+    return 2 * 6_371_000 * Math.asin(Math.sqrt(h));
+}
+/**
+ * The pass's Lock Screen locations as Google `merchantLocations`. An event
+ * ticket's venue is already on its Google class, so points at the venue are left
+ * out. Google writes its own notification text, so messages are not sent.
+ */
+export function googleLocations(def, locations) {
+    const venue = def.type === 'event_ticket' ? def.event?.venue?.location : undefined;
+    return locations
+        .filter((point) => !venue || metresBetween(point, venue) > NEAR_VENUE_METRES)
+        .map(({ latitude, longitude }) => ({ latitude, longitude }));
+}
+/** Google shows the event and the seat natively, so their fields aren't text rows. */
+export function googleShowsNatively(def, field) {
+    return def.type === 'event_ticket' && (field.binding === 'event' || field.googleRole !== undefined);
+}
+/** An event-bound field's value: the event's, else a preview sample. */
+export function eventFieldValue(def, field, mode) {
+    const value = eventValue(field, def.event);
+    if (value !== undefined)
+        return value;
+    if (mode === 'preview')
+        return field.sampleValue ?? '';
+    return undefined;
+}

package/dist/compiler/loyalty-card.d.ts

@@ -0,0 +1,28 @@
+import type { GoogleLoyalty } from 'passmint';
+import { type FieldDef, type FieldValue, type TemplateDefinition } from '../contract/index.js';
+export type LoyaltyCardDefinition = Extract<TemplateDefinition, {
+    type: 'stamp_card' | 'points_card';
+}>;
+type ValueOf = (field: FieldDef) => FieldValue | undefined;
+export declare function isLoyaltyCard(def: TemplateDefinition): def is LoyaltyCardDefinition;
+/**
+ * The balance a loyalty card shows, in its field and as Google's balance: the stamp
+ * count ("7 / 10") or the points ("350 / 1,000"). A compile without a points balance
+ * shows the template's starting balance.
+ */
+export declare function loyaltyBalanceText(def: TemplateDefinition, stampCount: number, pointsBalance: number | undefined): string | undefined;
+export type LoyaltyFieldTexts = Partial<Record<'stamps' | 'points' | 'stampsLeft' | 'pointsToGoal', string>>;
+/** What each loyalty-bound field shows on this pass. */
+export declare function loyaltyFieldTexts(def: TemplateDefinition, stampCount: number, pointsBalance: number | undefined): LoyaltyFieldTexts;
+/** Google shows the balance as its loyalty balance and the member fields as the account. */
+export declare function loyaltyShowsNatively(def: TemplateDefinition, field: FieldDef): boolean;
+/** The balance field's label (else "Stamps" / "Points") and the Member name field. */
+export declare function googleLoyalty(def: LoyaltyCardDefinition, balance: string, valueOf: ValueOf): GoogleLoyalty;
+/** Google's account id, from the Member ID field; undefined keeps passmint's (the serial). */
+export declare function googleAccountId(def: LoyaltyCardDefinition, valueOf: ValueOf): string | undefined;
+/** The loyalty class's names: the Google-only texts, else logo text, else the organization. */
+export declare function googleProgramNames(def: LoyaltyCardDefinition): {
+    issuerName: string;
+    programName: string;
+};
+export {};

package/dist/compiler/loyalty-card.js

@@ -0,0 +1,70 @@
+import { formatPoints, pointsBalanceText, stampCountText, } from '../contract/index.js';
+const BALANCE_FIELD = {
+    stamp_card: { binding: 'stamps', label: 'Stamps' },
+    points_card: { binding: 'points', label: 'Points' },
+};
+export function isLoyaltyCard(def) {
+    return def.type === 'stamp_card' || def.type === 'points_card';
+}
+/**
+ * The balance a loyalty card shows, in its field and as Google's balance: the stamp
+ * count ("7 / 10") or the points ("350 / 1,000"). A compile without a points balance
+ * shows the template's starting balance.
+ */
+export function loyaltyBalanceText(def, stampCount, pointsBalance) {
+    if (def.type === 'stamp_card')
+        return stampCountText(stampCount, def.config.stamps.total);
+    if (def.type === 'points_card') {
+        return pointsBalanceText(pointsBalance ?? def.config.points.starting, def.config.points.goal);
+    }
+    return undefined;
+}
+/** What each loyalty-bound field shows on this pass. */
+export function loyaltyFieldTexts(def, stampCount, pointsBalance) {
+    const balance = loyaltyBalanceText(def, stampCount, pointsBalance);
+    if (def.type === 'stamp_card') {
+        return { stamps: balance, stampsLeft: String(Math.max(def.config.stamps.total - stampCount, 0)) };
+    }
+    if (def.type === 'points_card') {
+        const { goal, starting } = def.config.points;
+        return {
+            points: balance,
+            ...(goal === undefined ? {} : { pointsToGoal: formatPoints(Math.max(goal - (pointsBalance ?? starting), 0)) }),
+        };
+    }
+    return {};
+}
+/** Google shows the balance as its loyalty balance and the member fields as the account. */
+export function loyaltyShowsNatively(def, field) {
+    return (isLoyaltyCard(def) &&
+        (field.binding === BALANCE_FIELD[def.type].binding ||
+            field.key === def.google.memberIdField ||
+            field.key === def.google.memberNameField));
+}
+function memberValue(def, key, valueOf) {
+    const field = key === undefined ? undefined : def.config.fields.find((f) => f.key === key);
+    const value = field ? valueOf(field) : undefined;
+    const text = value === undefined ? '' : String(value).trim();
+    return text === '' ? undefined : text;
+}
+/** The balance field's label (else "Stamps" / "Points") and the Member name field. */
+export function googleLoyalty(def, balance, valueOf) {
+    const { binding, label } = BALANCE_FIELD[def.type];
+    const balanceField = def.config.fields.find((f) => f.binding === binding);
+    return {
+        points: { label: balanceField?.label ?? label, balance },
+        accountName: memberValue(def, def.google.memberNameField, valueOf) ?? null,
+    };
+}
+/** Google's account id, from the Member ID field; undefined keeps passmint's (the serial). */
+export function googleAccountId(def, valueOf) {
+    return memberValue(def, def.google.memberIdField, valueOf);
+}
+/** The loyalty class's names: the Google-only texts, else logo text, else the organization. */
+export function googleProgramNames(def) {
+    const fallback = def.logoText?.trim() || def.organizationName;
+    return {
+        issuerName: def.google.issuerName ?? fallback,
+        programName: def.google.programName ?? fallback,
+    };
+}

package/dist/compiler/passmint-compiler.d.ts

@@ -0,0 +1,118 @@
+import { type PassInput } from 'passmint';
+import { type BarcodeConfig, type BarcodeFormat, type FieldDef, type FieldValue, type Relevance, type TemplateDefinition } from '../contract/index.js';
+import { type StampRender } from './stamp-card.js';
+export type { StampRender } from './stamp-card.js';
+/**
+ * This module is the ONLY place that imports `passmint`. It resolves a
+ * validated TemplateDefinition (plus resolved assets and, at issuance, per-pass
+ * values) into a concrete passmint pass — the adapter boundary the rest of the
+ * app depends on. Signing lives in a later feature; here we only build/render.
+ */
+export type Platform = 'apple' | 'google';
+/** Apple needs inline bytes; Google needs an HTTPS URL. A slot must provide the one its platform uses. */
+export interface ResolvedAsset {
+    bytes?: Uint8Array;
+    url?: string;
+    /** The image fitted to the poster logo box (126×30 pt), when this asset is the poster logo. */
+    posterLogoBytes?: Uint8Array;
+}
+export type ResolvedAssets = Record<string, ResolvedAsset>;
+/** Apple signing identity is injected at issuance (Feature 2); previews use placeholders. */
+export interface IssuanceContext {
+    passTypeIdentifier: string;
+    teamIdentifier: string;
+    serialNumber: string;
+}
+export declare const PREVIEW_ISSUANCE: IssuanceContext;
+export interface CompileOptions {
+    platform: Platform;
+    assets: ResolvedAssets;
+    values?: Record<string, FieldValue>;
+    barcodeValue?: string;
+    /** Per-pass Featured Action links by action id. */
+    actionLinks?: Record<string, string>;
+    /** The pass's own Lock Screen relevance; its lists replace the template's. Apple-only. */
+    relevance?: Relevance | null;
+    /** The pass holder; Google event tickets show it as the ticket holder. */
+    holderName?: string | null;
+    mode?: 'preview' | 'issue';
+    issuance?: IssuanceContext;
+    /** Numeric Google Wallet issuer id. Placeholder in preview; real value at issuance (Feature 2). */
+    issuerId?: string;
+    /** Google class id suffix (`{issuerId}.{classSuffix}`). One stable class per template. */
+    classSuffix?: string;
+    /** Google object id suffix (`{issuerId}.{objectSuffix}`). The globally unique pass id. */
+    objectSuffix?: string;
+    /** Apple-only; ignored for Google. Embedding it makes the pass register for updates. */
+    webService?: {
+        url: string;
+        authToken: string;
+    };
+    /** Apple-only `changeMessage` per field id; each must contain `%@`. */
+    changeMessages?: Record<string, string>;
+    /** Apple-only. When set, the reserved notification fields lead the back of the pass. */
+    walletMessages?: WalletMessages;
+    /** Apple `voided: true`; Google object state `INACTIVE`. */
+    voided?: boolean;
+    /** A stamp card's count and drawn stamps; stand-ins are used when absent. */
+    stamps?: StampRender;
+    /** A points card's balance; the template's starting balance when absent. */
+    points?: number;
+}
+export interface WalletMessages {
+    announcement?: string;
+    personal?: string;
+}
+export declare const WALLET_MESSAGE_FIELDS: readonly [{
+    readonly kind: "announcement";
+    readonly key: "tapace_announcement";
+    readonly label: "Announcements";
+    readonly placeholder: "No announcements yet";
+}, {
+    readonly kind: "personal";
+    readonly key: "tapace_message";
+    readonly label: "Message for you";
+    readonly placeholder: "No messages yet";
+}];
+export declare class AssetResolutionError extends Error {
+}
+/**
+ * Stand-in assets for structural validation (field counts, colors, required
+ * icon, barcode) without reading real bytes. Ownership + image validity are
+ * checked separately at upload/reference time; real bytes/URLs are needed only
+ * at signing (a later feature).
+ */
+export declare function placeholderAssets(ids: string[]): ResolvedAssets;
+export declare function resolveFieldValue(field: FieldDef, values: Record<string, FieldValue>, mode: 'preview' | 'issue'): FieldValue | undefined;
+/**
+ * The barcode message an already-issued pass renders, honoring the `passValue`
+ * serial-number fallback. Shared by the sign path and the deployment engine so the
+ * fallback lives in one place.
+ */
+export declare function resolveIssuedBarcodeMessage(barcode: BarcodeConfig, barcodeValue: string | null | undefined, serialNumber: string): string;
+/**
+ * Whether passmint accepts a barcode payload for a format/encoding — used by the
+ * deployment engine to decide when a format/encoding change makes an existing
+ * payload unrenderable (omit until corrected). Everything but the barcode is a
+ * valid placeholder, so a schema error isolates the barcode.
+ */
+export declare function barcodeRenderable(format: BarcodeFormat, message: string, messageEncoding?: string): boolean;
+/** Build the validated passmint pass for one platform. Throws PassmintSchemaError on invalid mappings. */
+export declare function compile(def: TemplateDefinition, options: CompileOptions): PassInput;
+/** The resolved barcode payload for preview/display, or undefined if no barcode. */
+export declare function previewBarcodeMessage(def: TemplateDefinition): string | undefined;
+export declare function renderApple(def: TemplateDefinition, options: Omit<CompileOptions, 'platform'>): import("passmint").AppleRenderedPass;
+export declare function renderGoogle(def: TemplateDefinition, options: Omit<CompileOptions, 'platform'>): import("passmint").GoogleSavePayload;
+export interface CompileIssue {
+    /** `template` marks a structural (pre-compile) issue that is not platform-specific. */
+    platform: Platform | 'template';
+    path: string;
+    message: string;
+}
+/**
+ * Compile each enabled platform and collect passmint's own schema issues.
+ * Used by the preview/validate endpoint so the designer surfaces native-limit
+ * violations (field counts, missing icon, bad color) the way it surfaces ours.
+ */
+export declare function collectCompileIssues(def: TemplateDefinition, options: Pick<CompileOptions, 'assets' | 'values' | 'mode' | 'issuance'>): CompileIssue[];
+export declare function toCompileIssues(platform: Platform, err: unknown): CompileIssue[];