@ketch.to/schema 0.0.0-stage → 0.1.0

package/dist/src/validate.d.ts

@@ -0,0 +1,505 @@
+import { type Card, type CardPatch, type NewCard, type NewWebhook, type OutcomeInput, type WebhookPayload } from "./types.js";
+export declare const cardSchema: {
+    $schema: string;
+    $id: string;
+    title: string;
+    description: string;
+    $defs: {
+        Duration: {
+            type: string;
+            description: string;
+            pattern: string;
+            examples: string[];
+        };
+        CardId: {
+            type: string;
+            pattern: string;
+            description: string;
+        };
+        ActionId: {
+            type: string;
+            pattern: string;
+            description: string;
+        };
+        ActionStyle: {
+            type: string;
+            enum: string[];
+            description: string;
+        };
+        Action: {
+            type: string;
+            additionalProperties: boolean;
+            required: string[];
+            properties: {
+                id: {
+                    $ref: string;
+                };
+                label: {
+                    type: string;
+                    minLength: number;
+                    maxLength: number;
+                };
+                style: {
+                    $ref: string;
+                    default: string;
+                };
+                input: {
+                    type: string;
+                    enum: string[];
+                    description: string;
+                };
+                snooze_for: {
+                    $ref: string;
+                    description: string;
+                };
+            };
+        };
+        Actions: {
+            type: string;
+            minItems: number;
+            maxItems: number;
+            items: {
+                $ref: string;
+            };
+        };
+        Source: {
+            type: string;
+            additionalProperties: boolean;
+            properties: {
+                app: {
+                    type: string;
+                    minLength: number;
+                    maxLength: number;
+                    description: string;
+                };
+                context: {
+                    type: string;
+                    minLength: number;
+                    maxLength: number;
+                };
+            };
+        };
+        Input: {
+            type: string;
+            additionalProperties: boolean;
+            properties: {
+                placeholder: {
+                    type: string;
+                    maxLength: number;
+                };
+                spawns: {
+                    type: string;
+                    default: boolean;
+                    description: string;
+                };
+            };
+        };
+        Recurrence: {
+            type: string;
+            additionalProperties: boolean;
+            required: string[];
+            properties: {
+                every: {
+                    $ref: string;
+                };
+            };
+        };
+        Kind: {
+            type: string;
+            enum: string[];
+            description: string;
+        };
+        Priority: {
+            type: string;
+            minimum: number;
+            maximum: number;
+            default: number;
+            description: string;
+        };
+        Link: {
+            type: string;
+            pattern: string;
+            maxLength: number;
+            description: string;
+        };
+        Meta: {
+            type: string;
+            description: string;
+        };
+        CardFields: {
+            type: string;
+            properties: {
+                title: {
+                    type: string;
+                    minLength: number;
+                    maxLength: number;
+                };
+                body: {
+                    type: string;
+                    maxLength: number;
+                    description: string;
+                };
+                source: {
+                    $ref: string;
+                };
+                link: {
+                    $ref: string;
+                };
+                priority: {
+                    $ref: string;
+                };
+                kind: {
+                    $ref: string;
+                    default: string;
+                };
+                actions: {
+                    $ref: string;
+                };
+                input: {
+                    $ref: string;
+                };
+                recurrence: {
+                    $ref: string;
+                };
+                show_after: {
+                    type: string[];
+                    format: string;
+                    description: string;
+                };
+                expires_at: {
+                    type: string[];
+                    format: string;
+                    description: string;
+                };
+                meta: {
+                    $ref: string;
+                };
+            };
+        };
+        NewCard: {
+            description: string;
+            allOf: {
+                $ref: string;
+            }[];
+            type: string;
+            additionalProperties: boolean;
+            required: string[];
+            properties: {
+                title: boolean;
+                body: boolean;
+                source: boolean;
+                link: boolean;
+                priority: boolean;
+                kind: boolean;
+                actions: boolean;
+                input: boolean;
+                recurrence: boolean;
+                show_after: boolean;
+                expires_at: boolean;
+                meta: boolean;
+            };
+        };
+        CardPatch: {
+            description: string;
+            type: string;
+            additionalProperties: boolean;
+            minProperties: number;
+            properties: {
+                title: {
+                    type: string;
+                    minLength: number;
+                    maxLength: number;
+                };
+                body: {
+                    type: string[];
+                    maxLength: number;
+                };
+                actions: {
+                    $ref: string;
+                };
+                show_after: {
+                    type: string[];
+                    format: string;
+                };
+                priority: {
+                    $ref: string;
+                };
+                link: {
+                    anyOf: ({
+                        $ref: string;
+                        type?: undefined;
+                    } | {
+                        type: string;
+                        $ref?: undefined;
+                    })[];
+                };
+                expires_at: {
+                    type: string[];
+                    format: string;
+                };
+                meta: {
+                    $ref: string;
+                };
+            };
+        };
+        Status: {
+            type: string;
+            enum: string[];
+            description: string;
+        };
+        Outcome: {
+            type: string;
+            additionalProperties: boolean;
+            required: string[];
+            properties: {
+                action: {
+                    $ref: string;
+                };
+                text: {
+                    type: string[];
+                    maxLength: number;
+                };
+                at: {
+                    type: string;
+                    format: string;
+                };
+                snoozed_until: {
+                    type: string[];
+                    format: string;
+                };
+            };
+        };
+        OutcomeInput: {
+            description: string;
+            type: string;
+            additionalProperties: boolean;
+            required: string[];
+            properties: {
+                action: {
+                    $ref: string;
+                };
+                text: {
+                    type: string[];
+                    maxLength: number;
+                };
+                snoozed_until: {
+                    type: string[];
+                    format: string;
+                    description: string;
+                };
+                spawn: {
+                    type: string;
+                    maxItems: number;
+                    items: {
+                        type: string;
+                        minLength: number;
+                        maxLength: number;
+                    };
+                    description: string;
+                };
+            };
+        };
+        Card: {
+            description: string;
+            allOf: {
+                $ref: string;
+            }[];
+            type: string;
+            additionalProperties: boolean;
+            required: string[];
+            properties: {
+                id: {
+                    $ref: string;
+                };
+                title: boolean;
+                body: boolean;
+                link: boolean;
+                priority: boolean;
+                kind: boolean;
+                actions: boolean;
+                input: boolean;
+                recurrence: boolean;
+                show_after: boolean;
+                expires_at: boolean;
+                meta: boolean;
+                source: {
+                    type: string;
+                    additionalProperties: boolean;
+                    required: string[];
+                    properties: {
+                        app: {
+                            type: string;
+                            minLength: number;
+                            maxLength: number;
+                        };
+                        context: {
+                            type: string;
+                            minLength: number;
+                            maxLength: number;
+                        };
+                    };
+                };
+                status: {
+                    $ref: string;
+                };
+                parent_id: {
+                    anyOf: ({
+                        $ref: string;
+                        type?: undefined;
+                    } | {
+                        type: string;
+                        $ref?: undefined;
+                    })[];
+                    description: string;
+                };
+                outcome: {
+                    anyOf: ({
+                        $ref: string;
+                        type?: undefined;
+                    } | {
+                        type: string;
+                        $ref?: undefined;
+                    })[];
+                    description: string;
+                };
+                created_at: {
+                    type: string;
+                    format: string;
+                };
+                updated_at: {
+                    type: string;
+                    format: string;
+                };
+                retired_at: {
+                    type: string[];
+                    format: string;
+                };
+            };
+        };
+        WebhookEvent: {
+            type: string;
+            enum: string[];
+        };
+        NewWebhook: {
+            type: string;
+            additionalProperties: boolean;
+            required: string[];
+            properties: {
+                url: {
+                    type: string;
+                    pattern: string;
+                    maxLength: number;
+                };
+                secret: {
+                    type: string;
+                    minLength: number;
+                    maxLength: number;
+                };
+                events: {
+                    type: string;
+                    minItems: number;
+                    uniqueItems: boolean;
+                    items: {
+                        $ref: string;
+                    };
+                };
+            };
+        };
+        Webhook: {
+            type: string;
+            additionalProperties: boolean;
+            required: string[];
+            properties: {
+                id: {
+                    type: string;
+                    pattern: string;
+                };
+                url: {
+                    type: string;
+                };
+                events: {
+                    type: string;
+                    items: {
+                        $ref: string;
+                    };
+                };
+                created_at: {
+                    type: string;
+                    format: string;
+                };
+            };
+        };
+        WebhookPayload: {
+            description: string;
+            type: string;
+            additionalProperties: boolean;
+            required: string[];
+            properties: {
+                id: {
+                    type: string;
+                    description: string;
+                };
+                event: {
+                    $ref: string;
+                };
+                at: {
+                    type: string;
+                    format: string;
+                };
+                card: {
+                    $ref: string;
+                };
+                outcome: {
+                    $ref: string;
+                };
+                parent: {
+                    $ref: string;
+                };
+            };
+            oneOf: ({
+                properties: {
+                    event: {
+                        const: string;
+                    };
+                    parent: boolean;
+                    outcome?: undefined;
+                };
+                required: string[];
+            } | {
+                properties: {
+                    event: {
+                        const: string;
+                    };
+                    outcome: boolean;
+                    parent?: undefined;
+                };
+                required: string[];
+            })[];
+        };
+    };
+};
+export interface ValidationError {
+    /** JSON pointer-ish path, e.g. "/actions/1/id". "" for the root. */
+    path: string;
+    message: string;
+}
+export type ValidationResult<T> = {
+    ok: true;
+    value: T;
+} | {
+    ok: false;
+    errors: ValidationError[];
+};
+/** Validate a producer payload for POST /cards. Does not apply kind defaults; see withKindDefaults. */
+export declare function validateNewCard(input: unknown): ValidationResult<NewCard>;
+/** Validate a full server-shaped card (what GET returns, what webhooks carry). */
+export declare function validateCard(input: unknown): ValidationResult<Card>;
+export declare function validateCardPatch(input: unknown): ValidationResult<CardPatch>;
+/**
+ * Validate an outcome against the card it's for: the action must be one of the
+ * card's actions or a reserved id; snooze-style actions need snoozed_until;
+ * required-input actions need text; spawn needs a spawning input.
+ */
+export declare function validateOutcomeInput(input: unknown, card?: Pick<Card, "actions" | "input">): ValidationResult<OutcomeInput>;
+export declare function validateNewWebhook(input: unknown): ValidationResult<NewWebhook>;
+export declare function validateWebhookPayload(input: unknown): ValidationResult<WebhookPayload>;

package/dist/src/validate.js

@@ -0,0 +1,92 @@
+import { Ajv2020 } from "ajv/dist/2020.js";
+import * as addFormatsModule from "ajv-formats";
+const addFormats = (addFormatsModule.default ?? addFormatsModule);
+import schema from "../card.schema.json" with { type: "json" };
+import { RESERVED_ACTION_IDS } from "./types.js";
+export const cardSchema = schema;
+const ajv = new Ajv2020({ allErrors: true, strict: true, strictRequired: false, allowUnionTypes: true });
+addFormats(ajv);
+ajv.addSchema(schema);
+function compile(def) {
+    return ajv.compile({ $ref: `${schema.$id}#/$defs/${def}` });
+}
+const validators = {
+    NewCard: compile("NewCard"),
+    Card: compile("Card"),
+    CardPatch: compile("CardPatch"),
+    OutcomeInput: compile("OutcomeInput"),
+    NewWebhook: compile("NewWebhook"),
+    WebhookPayload: compile("WebhookPayload"),
+};
+function toErrors(errs) {
+    return (errs ?? []).map((e) => ({
+        path: e.instancePath,
+        message: e.keyword === "additionalProperties" ? `unknown property "${e.params.additionalProperty}"` : e.message ?? e.keyword,
+    }));
+}
+/** Semantic checks the JSON Schema can't express. */
+function checkActions(actions, path) {
+    if (!Array.isArray(actions))
+        return [];
+    const errors = [];
+    const seen = new Set();
+    actions.forEach((a, i) => {
+        if (a.id && seen.has(a.id))
+            errors.push({ path: `${path}/${i}/id`, message: `duplicate action id "${a.id}"` });
+        if (a.id)
+            seen.add(a.id);
+        if (a.snooze_for !== undefined && a.style !== "snooze") {
+            errors.push({ path: `${path}/${i}/snooze_for`, message: 'snooze_for is only allowed when style is "snooze"' });
+        }
+    });
+    return errors;
+}
+function run(v, input, extra = () => []) {
+    if (!v(input))
+        return { ok: false, errors: toErrors(v.errors) };
+    const errors = extra(input);
+    return errors.length ? { ok: false, errors } : { ok: true, value: input };
+}
+/** Validate a producer payload for POST /cards. Does not apply kind defaults; see withKindDefaults. */
+export function validateNewCard(input) {
+    return run(validators.NewCard, input, (c) => checkActions(c.actions, "/actions"));
+}
+/** Validate a full server-shaped card (what GET returns, what webhooks carry). */
+export function validateCard(input) {
+    return run(validators.Card, input, (c) => checkActions(c.actions, "/actions"));
+}
+export function validateCardPatch(input) {
+    return run(validators.CardPatch, input, (c) => checkActions(c.actions, "/actions"));
+}
+/**
+ * Validate an outcome against the card it's for: the action must be one of the
+ * card's actions or a reserved id; snooze-style actions need snoozed_until;
+ * required-input actions need text; spawn needs a spawning input.
+ */
+export function validateOutcomeInput(input, card) {
+    return run(validators.OutcomeInput, input, (o) => {
+        if (!card)
+            return [];
+        const errors = [];
+        const action = card.actions.find((a) => a.id === o.action);
+        const reserved = RESERVED_ACTION_IDS.includes(o.action);
+        if (!action && !reserved)
+            errors.push({ path: "/action", message: `"${o.action}" is not an action on this card` });
+        const isSnooze = o.action === "snooze" || action?.style === "snooze";
+        if (isSnooze && !o.snoozed_until)
+            errors.push({ path: "/snoozed_until", message: "required for snooze actions" });
+        if (!isSnooze && o.snoozed_until)
+            errors.push({ path: "/snoozed_until", message: "only allowed for snooze actions" });
+        if (action?.input === "required" && !o.text?.trim())
+            errors.push({ path: "/text", message: `action "${o.action}" requires text` });
+        if (o.spawn?.length && !card.input?.spawns)
+            errors.push({ path: "/spawn", message: "card has no spawning input" });
+        return errors;
+    });
+}
+export function validateNewWebhook(input) {
+    return run(validators.NewWebhook, input);
+}
+export function validateWebhookPayload(input) {
+    return run(validators.WebhookPayload, input);
+}

package/package.json

@@ -1,6 +1,49 @@
 {
   "name": "@ketch.to/schema",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.0",
+  "description": "Ketch card JSON Schema, TypeScript types, validators and fixtures",
+  "type": "module",
+  "main": "./dist/src/index.js",
+  "types": "./dist/src/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/src/index.d.ts",
+      "import": "./dist/src/index.js"
+    },
+    "./card.schema.json": "./card.schema.json",
+    "./fixtures": {
+      "types": "./dist/fixtures/index.d.ts",
+      "import": "./dist/fixtures/index.js"
+    }
+  },
+  "files": [
+    "dist/src",
+    "dist/fixtures",
+    "card.schema.json",
+    "README.md"
+  ],
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "test": "vitest run",
+    "gen:swift": "tsx scripts/gen-swift.ts && tsx scripts/export-fixtures.ts",
+    "prepublishOnly": "npm run build && npm test"
+  },
+  "dependencies": {
+    "ajv": "^8.17.1",
+    "ajv-formats": "^3.0.1"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "homepage": "https://ketch.to",
+  "engines": {
+    "node": ">=18"
+  },
+  "keywords": [
+    "ketch",
+    "json-schema",
+    "cards",
+    "agents"
+  ]
+}