@owask/tapace-templates 0.0.0-stage → 0.1.0

package/dist/contract/points.js

@@ -0,0 +1,86 @@
+import { z } from 'zod';
+/** The largest balance, limit or change a points card stores (`DECIMAL(9,2)`). */
+export const MAX_POINTS = 9_999_999.99;
+function hasAtMostTwoDecimals(value) {
+    const cents = value * 100;
+    return Math.abs(cents - Math.round(cents)) < 1e-6;
+}
+const outOfBounds = 'Points must be between -9,999,999.99 and 9,999,999.99.';
+export const PointsAmountSchema = z
+    .number()
+    .min(-MAX_POINTS, outOfBounds)
+    .max(MAX_POINTS, outOfBounds)
+    .refine(hasAtMostTwoDecimals, 'Points can have at most 2 decimal places.');
+/**
+ * A points card's range and starting balance. Every limit is optional. The goal
+ * caps the balance; `max` only limits it when there is no goal, so a goal above
+ * it is rejected rather than ignored.
+ */
+export const PointsSettingsSchema = z
+    .strictObject({
+    min: PointsAmountSchema.optional(),
+    max: PointsAmountSchema.optional(),
+    goal: PointsAmountSchema.optional(),
+    starting: PointsAmountSchema,
+})
+    .superRefine((p, ctx) => {
+    if (p.goal !== undefined && p.max !== undefined && p.goal > p.max) {
+        ctx.addIssue({ code: 'custom', message: 'The goal can be at most the maximum.', path: ['goal'] });
+    }
+    const top = pointsCap(p);
+    if (p.min !== undefined && top !== undefined && p.min > top) {
+        ctx.addIssue({
+            code: 'custom',
+            message: p.goal !== undefined ? 'The minimum can be at most the goal.' : 'The minimum can be at most the maximum.',
+            path: ['min'],
+        });
+    }
+    if (p.min !== undefined && p.starting < p.min) {
+        ctx.addIssue({ code: 'custom', message: 'The starting balance is below the minimum.', path: ['starting'] });
+    }
+    if (top !== undefined && p.starting > top) {
+        ctx.addIssue({
+            code: 'custom',
+            message: p.goal !== undefined ? 'The starting balance is above the goal.' : 'The starting balance is above the maximum.',
+            path: ['starting'],
+        });
+    }
+});
+const notificationText = z.string().trim().min(1).max(200);
+/**
+ * What a points change that notifies says. `{balance}` stands for the balance
+ * text ("350 / 1,000") and `{change}` for the requested amount ("+50"). Apple's
+ * message is the points field's change message, so it must contain `{balance}`;
+ * without a points field it fills the pass's message field instead. The optional
+ * `goal…` texts replace them when the change reaches the goal; Apple's always
+ * goes in the message field, so it needs no `{balance}`.
+ */
+export const PointsNotificationsSchema = z.strictObject({
+    apple: notificationText
+        .refine((text) => text.includes('{balance}'), 'Include {balance} where the balance goes.')
+        .optional(),
+    googleTitle: notificationText.optional(),
+    googleBody: notificationText.optional(),
+    goalApple: notificationText.optional(),
+    goalGoogleTitle: notificationText.optional(),
+    goalGoogleBody: notificationText.optional(),
+});
+/** The highest balance: the goal when set, else the maximum. */
+export function pointsCap(points) {
+    return points.goal ?? points.max;
+}
+/** "1,250", "12.50", "-9,999,999.99": decimals only on numbers that have them. */
+export function formatPoints(value) {
+    return new Intl.NumberFormat('en-US', {
+        minimumFractionDigits: Number.isInteger(value) ? 0 : 2,
+        maximumFractionDigits: 2,
+    }).format(value);
+}
+/** "350 / 1,000" with a goal, "350" without. */
+export function pointsBalanceText(balance, goal) {
+    return goal === undefined ? formatPoints(balance) : `${formatPoints(balance)} / ${formatPoints(goal)}`;
+}
+/** A change with its sign: "+50", "−20" (a true minus, as device-tested). */
+export function pointsChangeText(change) {
+    return change < 0 ? `−${formatPoints(-change)}` : `+${formatPoints(change)}`;
+}

package/dist/contract/primitives.d.ts

@@ -0,0 +1,26 @@
+import { z } from 'zod';
+/** `#RGB` or `#RRGGBB`. Passmint also accepts `rgb(...)`; TapAce standardises on hex. */
+export declare const HexColorSchema: z.ZodString;
+/** An `asset_…` id owned by the same organization as the template. */
+export declare const AssetRefSchema: z.ZodString;
+export declare const BarcodeFormatSchema: z.ZodEnum<{
+    qr: "qr";
+    pdf417: "pdf417";
+    aztec: "aztec";
+    code128: "code128";
+}>;
+export type BarcodeFormat = z.infer<typeof BarcodeFormatSchema>;
+export declare const BarcodeEncodingSchema: z.ZodEnum<{
+    "iso-8859-1": "iso-8859-1";
+    "utf-8": "utf-8";
+    "utf-16": "utf-16";
+}>;
+export declare const TextAlignmentSchema: z.ZodEnum<{
+    left: "left";
+    center: "center";
+    right: "right";
+    natural: "natural";
+}>;
+/** A field value. Passmint accepts string or number; TapAce preserves both. */
+export declare const FieldValueSchema: z.ZodUnion<readonly [z.ZodString, z.ZodNumber]>;
+export type FieldValue = z.infer<typeof FieldValueSchema>;

package/dist/contract/primitives.js

@@ -0,0 +1,14 @@
+import { z } from 'zod';
+/** `#RGB` or `#RRGGBB`. Passmint also accepts `rgb(...)`; TapAce standardises on hex. */
+export const HexColorSchema = z
+    .string()
+    .regex(/^#([0-9a-fA-F]{3}|[0-9a-fA-F]{6})$/, 'Expected a hex color like #18566A');
+/** An `asset_…` id owned by the same organization as the template. */
+export const AssetRefSchema = z
+    .string()
+    .regex(/^asset_[A-Za-z0-9_-]+$/, 'Expected an asset id');
+export const BarcodeFormatSchema = z.enum(['qr', 'pdf417', 'aztec', 'code128']);
+export const BarcodeEncodingSchema = z.enum(['iso-8859-1', 'utf-8', 'utf-16']);
+export const TextAlignmentSchema = z.enum(['left', 'center', 'right', 'natural']);
+/** A field value. Passmint accepts string or number; TapAce preserves both. */
+export const FieldValueSchema = z.union([z.string(), z.number()]);

package/dist/contract/relevance.d.ts

@@ -0,0 +1,54 @@
+import { z } from 'zod';
+export declare const MAX_RELEVANT_LOCATIONS = 10;
+export declare const MAX_RELEVANT_DATES = 10;
+export declare const RELEVANCE_MESSAGE_MAX = 120;
+/** Wallet needs the timezone: older iOS silently drops a date without one. */
+export declare const DateTimeSchema: z.ZodString;
+export declare const RelevantLocationSchema: z.ZodObject<{
+    latitude: z.ZodNumber;
+    longitude: z.ZodNumber;
+    message: z.ZodOptional<z.ZodString>;
+}, z.core.$strict>;
+export type RelevantLocation = z.infer<typeof RelevantLocationSchema>;
+export declare const RelevantDateSchema: z.ZodObject<{
+    start: z.ZodString;
+    end: z.ZodString;
+}, z.core.$strict>;
+export type RelevantDate = z.infer<typeof RelevantDateSchema>;
+/**
+ * Apple Lock Screen relevance ("When and where"). On a pass, each list that is
+ * present replaces the template's; `[]` means none for that pass.
+ */
+export declare const RelevanceSchema: z.ZodObject<{
+    locations: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        latitude: z.ZodNumber;
+        longitude: z.ZodNumber;
+        message: z.ZodOptional<z.ZodString>;
+    }, z.core.$strict>>>;
+    dates: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        start: z.ZodString;
+        end: z.ZodString;
+    }, z.core.$strict>>>;
+}, z.core.$strict>;
+export type Relevance = z.infer<typeof RelevanceSchema>;
+export declare function isTimeZone(name: string): boolean;
+/** The template's lists, plus the timezone the dashboard shows and enters window times in. */
+export declare const TemplateRelevanceSchema: z.ZodObject<{
+    locations: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        latitude: z.ZodNumber;
+        longitude: z.ZodNumber;
+        message: z.ZodOptional<z.ZodString>;
+    }, z.core.$strict>>>;
+    dates: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        start: z.ZodString;
+        end: z.ZodString;
+    }, z.core.$strict>>>;
+    timezone: z.ZodOptional<z.ZodString>;
+}, z.core.$strict>;
+export type TemplateRelevance = z.infer<typeof TemplateRelevanceSchema>;
+export interface ResolvedRelevance {
+    locations: RelevantLocation[];
+    dates: RelevantDate[];
+}
+/** A pass's stored relevance; anything unreadable counts as none, so the template's applies. */
+export declare function storedRelevance(raw: unknown): Relevance | null;

package/dist/contract/relevance.js

@@ -0,0 +1,52 @@
+import { z } from 'zod';
+export const MAX_RELEVANT_LOCATIONS = 10;
+export const MAX_RELEVANT_DATES = 10;
+export const RELEVANCE_MESSAGE_MAX = 120;
+/** Wallet needs the timezone: older iOS silently drops a date without one. */
+export const DateTimeSchema = z
+    .string()
+    .regex(/^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(\.\d+)?(Z|[+-]\d{2}:\d{2})$/, 'Expected a date and time with a timezone, like 2026-11-02T18:00:00+05:30.');
+function coordinate(name, limit) {
+    const error = `Enter a ${name} from -${limit} to ${limit}.`;
+    return z.number({ error }).min(-limit, { error }).max(limit, { error });
+}
+export const RelevantLocationSchema = z.strictObject({
+    latitude: coordinate('latitude', 90),
+    longitude: coordinate('longitude', 180),
+    message: z.string().trim().min(1).max(RELEVANCE_MESSAGE_MAX).optional(),
+});
+export const RelevantDateSchema = z
+    .strictObject({ start: DateTimeSchema, end: DateTimeSchema })
+    .refine((window) => Date.parse(window.end) > Date.parse(window.start), {
+    message: 'A date window must end after it starts.',
+    path: ['end'],
+});
+/**
+ * Apple Lock Screen relevance ("When and where"). On a pass, each list that is
+ * present replaces the template's; `[]` means none for that pass.
+ */
+export const RelevanceSchema = z.strictObject({
+    locations: z.array(RelevantLocationSchema).max(MAX_RELEVANT_LOCATIONS).optional(),
+    dates: z.array(RelevantDateSchema).max(MAX_RELEVANT_DATES).optional(),
+});
+export function isTimeZone(name) {
+    try {
+        new Intl.DateTimeFormat('en', { timeZone: name });
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/** The template's lists, plus the timezone the dashboard shows and enters window times in. */
+export const TemplateRelevanceSchema = RelevanceSchema.extend({
+    timezone: z
+        .string()
+        .refine(isTimeZone, 'Expected a timezone like Asia/Colombo.')
+        .optional(),
+});
+/** A pass's stored relevance; anything unreadable counts as none, so the template's applies. */
+export function storedRelevance(raw) {
+    const parsed = RelevanceSchema.safeParse(raw);
+    return parsed.success ? parsed.data : null;
+}

package/dist/contract/stamps.d.ts

@@ -0,0 +1,91 @@
+import { z } from 'zod';
+export declare const MAX_STAMPS = 10;
+/** Built-in stamps, drawn from Phosphor icons of the same name. */
+export declare const STAMP_ICONS: readonly ["coffee", "star", "heart", "check", "gift", "scissors", "pizza", "sparkle"];
+export type StampIcon = (typeof STAMP_ICONS)[number];
+/**
+ * How stamps are drawn on the iOS 27 poster. The background is the template's
+ * poster artwork or its own colour (left out, the pass background). The disc sits
+ * behind each stamp so it stays readable on any artwork.
+ */
+export declare const StampPosterSettingsSchema: z.ZodObject<{
+    background: z.ZodDiscriminatedUnion<[z.ZodObject<{
+        kind: z.ZodLiteral<"artwork">;
+    }, z.core.$strict>, z.ZodObject<{
+        kind: z.ZodLiteral<"color">;
+        color: z.ZodOptional<z.ZodString>;
+    }, z.core.$strict>], "kind">;
+    discColor: z.ZodString;
+    discOpacity: z.ZodNumber;
+}, z.core.$strict>;
+export type StampPosterSettings = z.infer<typeof StampPosterSettingsSchema>;
+/**
+ * How a stamp card draws its stamps. Built-in icons are tinted with `earnedColor`
+ * and `emptyColor`; an uploaded stamp keeps its own colours. `emptyStyle` is how
+ * an unearned slot looks when there is no `emptyAssetId`. A background colour left
+ * out follows the pass background.
+ */
+export declare const StampSettingsSchema: z.ZodObject<{
+    total: z.ZodNumber;
+    perRow: z.ZodNumber;
+    stamp: z.ZodDiscriminatedUnion<[z.ZodObject<{
+        kind: z.ZodLiteral<"icon">;
+        icon: z.ZodEnum<{
+            check: "check";
+            coffee: "coffee";
+            star: "star";
+            heart: "heart";
+            gift: "gift";
+            scissors: "scissors";
+            pizza: "pizza";
+            sparkle: "sparkle";
+        }>;
+    }, z.core.$strict>, z.ZodObject<{
+        kind: z.ZodLiteral<"image">;
+        assetId: z.ZodString;
+    }, z.core.$strict>], "kind">;
+    emptyAssetId: z.ZodOptional<z.ZodString>;
+    emptyStyle: z.ZodEnum<{
+        faded: "faded";
+        ring: "ring";
+        both: "both";
+    }>;
+    earnedColor: z.ZodString;
+    emptyColor: z.ZodString;
+    background: z.ZodDiscriminatedUnion<[z.ZodObject<{
+        kind: z.ZodLiteral<"color">;
+        color: z.ZodOptional<z.ZodString>;
+    }, z.core.$strict>, z.ZodObject<{
+        kind: z.ZodLiteral<"image">;
+        assetId: z.ZodString;
+    }, z.core.$strict>], "kind">;
+    poster: z.ZodOptional<z.ZodObject<{
+        background: z.ZodDiscriminatedUnion<[z.ZodObject<{
+            kind: z.ZodLiteral<"artwork">;
+        }, z.core.$strict>, z.ZodObject<{
+            kind: z.ZodLiteral<"color">;
+            color: z.ZodOptional<z.ZodString>;
+        }, z.core.$strict>], "kind">;
+        discColor: z.ZodString;
+        discOpacity: z.ZodNumber;
+    }, z.core.$strict>>;
+}, z.core.$strict>;
+export type StampSettings = z.infer<typeof StampSettingsSchema>;
+/**
+ * What a stamp change that notifies says. `%@` stands for the count text
+ * ("7 / 10"). Apple's message is the count field's change message, so it must
+ * contain `%@`; without a count field it fills the pass's message field instead.
+ * The optional `full…` texts replace them when the change fills the card; Apple's
+ * always goes in the message field, so it needs no `%@`.
+ */
+export declare const StampNotificationsSchema: z.ZodObject<{
+    apple: z.ZodOptional<z.ZodString>;
+    googleTitle: z.ZodOptional<z.ZodString>;
+    googleBody: z.ZodOptional<z.ZodString>;
+    fullApple: z.ZodOptional<z.ZodString>;
+    fullGoogleTitle: z.ZodOptional<z.ZodString>;
+    fullGoogleBody: z.ZodOptional<z.ZodString>;
+}, z.core.$strict>;
+export type StampNotifications = z.infer<typeof StampNotificationsSchema>;
+export declare function stampCountText(count: number, total: number): string;
+export declare function stampAssetIds(stamps: StampSettings): string[];

package/dist/contract/stamps.js

@@ -0,0 +1,89 @@
+import { z } from 'zod';
+import { AssetRefSchema, HexColorSchema } from './primitives.js';
+export const MAX_STAMPS = 10;
+/** Built-in stamps, drawn from Phosphor icons of the same name. */
+export const STAMP_ICONS = [
+    'coffee',
+    'star',
+    'heart',
+    'check',
+    'gift',
+    'scissors',
+    'pizza',
+    'sparkle',
+];
+const stampCount = z.number().int().min(1).max(MAX_STAMPS);
+/** An uploaded image the designer may not have yet, with a message saying so. */
+const uploaded = (message) => z.string().regex(/^asset_[A-Za-z0-9_-]+$/, message);
+/**
+ * How stamps are drawn on the iOS 27 poster. The background is the template's
+ * poster artwork or its own colour (left out, the pass background). The disc sits
+ * behind each stamp so it stays readable on any artwork.
+ */
+export const StampPosterSettingsSchema = z.strictObject({
+    background: z.discriminatedUnion('kind', [
+        z.strictObject({ kind: z.literal('artwork') }),
+        z.strictObject({ kind: z.literal('color'), color: HexColorSchema.optional() }),
+    ]),
+    discColor: HexColorSchema,
+    discOpacity: z.number().min(0).max(1),
+});
+/**
+ * How a stamp card draws its stamps. Built-in icons are tinted with `earnedColor`
+ * and `emptyColor`; an uploaded stamp keeps its own colours. `emptyStyle` is how
+ * an unearned slot looks when there is no `emptyAssetId`. A background colour left
+ * out follows the pass background.
+ */
+export const StampSettingsSchema = z
+    .strictObject({
+    total: stampCount,
+    perRow: stampCount,
+    stamp: z.discriminatedUnion('kind', [
+        z.strictObject({ kind: z.literal('icon'), icon: z.enum(STAMP_ICONS) }),
+        z.strictObject({ kind: z.literal('image'), assetId: uploaded('Upload a stamp image.') }),
+    ]),
+    emptyAssetId: AssetRefSchema.optional(),
+    emptyStyle: z.enum(['faded', 'ring', 'both']),
+    earnedColor: HexColorSchema,
+    emptyColor: HexColorSchema,
+    background: z.discriminatedUnion('kind', [
+        z.strictObject({ kind: z.literal('color'), color: HexColorSchema.optional() }),
+        z.strictObject({ kind: z.literal('image'), assetId: uploaded('Upload a strip image.') }),
+    ]),
+    poster: StampPosterSettingsSchema.optional(),
+})
+    .refine((s) => s.perRow <= s.total, {
+    message: 'Stamps per row can be at most the number of stamps.',
+    path: ['perRow'],
+});
+const notificationText = z.string().trim().min(1).max(200);
+/**
+ * What a stamp change that notifies says. `%@` stands for the count text
+ * ("7 / 10"). Apple's message is the count field's change message, so it must
+ * contain `%@`; without a count field it fills the pass's message field instead.
+ * The optional `full…` texts replace them when the change fills the card; Apple's
+ * always goes in the message field, so it needs no `%@`.
+ */
+export const StampNotificationsSchema = z.strictObject({
+    apple: notificationText
+        .refine((text) => text.includes('%@'), 'Include %@ where the stamp count goes.')
+        .optional(),
+    googleTitle: notificationText.optional(),
+    googleBody: notificationText.optional(),
+    fullApple: notificationText.optional(),
+    fullGoogleTitle: notificationText.optional(),
+    fullGoogleBody: notificationText.optional(),
+});
+export function stampCountText(count, total) {
+    return `${count} / ${total}`;
+}
+export function stampAssetIds(stamps) {
+    const ids = [];
+    if (stamps.stamp.kind === 'image')
+        ids.push(stamps.stamp.assetId);
+    if (stamps.emptyAssetId)
+        ids.push(stamps.emptyAssetId);
+    if (stamps.background.kind === 'image')
+        ids.push(stamps.background.assetId);
+    return ids;
+}

package/dist/contract/upgrade.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Convert a schema version 1 definition (fields grouped by Apple slot) to
+ * version 2 (one field list plus a standard layout that places them by key), and
+ * move "When and where" from where it was first stored (`apple.relevance`) to the
+ * top level. Anything else is returned unchanged for the schema to judge.
+ */
+export declare function upgradeDefinition(input: unknown): unknown;

package/dist/contract/upgrade.js

@@ -0,0 +1,39 @@
+import { STANDARD_SLOTS } from './fields.js';
+const isObject = (value) => typeof value === 'object' && value !== null && !Array.isArray(value);
+/**
+ * Convert a schema version 1 definition (fields grouped by Apple slot) to
+ * version 2 (one field list plus a standard layout that places them by key), and
+ * move "When and where" from where it was first stored (`apple.relevance`) to the
+ * top level. Anything else is returned unchanged for the schema to judge.
+ */
+export function upgradeDefinition(input) {
+    return moveRelevance(upgradeVersion1(input));
+}
+function moveRelevance(input) {
+    if (!isObject(input) || !isObject(input.apple) || !('relevance' in input.apple))
+        return input;
+    const { relevance, ...apple } = input.apple;
+    return { ...input, apple, ...(input.relevance === undefined ? { relevance } : {}) };
+}
+function upgradeVersion1(input) {
+    if (!isObject(input) || input.schemaVersion !== 1)
+        return input;
+    const config = isObject(input.config) ? input.config : {};
+    const groups = isObject(config.fields) ? config.fields : {};
+    const fields = [];
+    const standard = {};
+    for (const slot of STANDARD_SLOTS) {
+        const group = Array.isArray(groups[slot]) ? groups[slot] : [];
+        standard[slot] = [];
+        for (const field of group) {
+            fields.push(field);
+            if (isObject(field) && typeof field.key === 'string')
+                standard[slot].push(field.key);
+        }
+    }
+    return {
+        ...input,
+        schemaVersion: 2,
+        config: { ...config, fields, layouts: { standard } },
+    };
+}

package/dist/public-api.d.ts

@@ -0,0 +1,4 @@
+export * from './contract/index.js';
+export * from './compiler/template-preview.js';
+export type { CompileIssue } from './compiler/passmint-compiler.js';
+export type { ApplePreview, BarcodePreview, FieldPreview, GoogleCardItemPreview, GoogleEventPreview, GoogleLoyaltyPreview, GooglePreview, PosterPreview, PreviewStyle, } from './compiler/preview-model.js';

package/dist/public-api.js

@@ -0,0 +1,2 @@
+export * from './contract/index.js';
+export * from './compiler/template-preview.js';

package/package.json

@@ -1,6 +1,22 @@
 {
   "name": "@owask/tapace-templates",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.0",
+  "description": "TapAce template contract and wallet preview compiler, shared by the API and the dashboard.",
+  "license": "UNLICENSED",
+  "type": "module",
+  "sideEffects": false,
+  "exports": {
+    ".": {
+      "types": "./dist/public-api.d.ts",
+      "default": "./dist/public-api.js"
+    }
+  },
+  "files": ["dist"],
+  "dependencies": {
+    "passmint": "npm:@owask/passmint@0.7.0-tapace.6",
+    "zod": "^4.5.4"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}