@ketch.to/schema 0.0.0-stage → 0.1.0

package/dist/fixtures/index.js

@@ -0,0 +1,120 @@
+export const doCard = {
+    title: "Reply to Shaina's marketing plan",
+    body: "You said 'more detailed reply to come' on Tue. The plan is in the thread; she asked about Q1 spend and the podcast idea.",
+    source: { app: "Claude", context: "Dosi-Smash Marketing Plan" },
+    link: "https://mail.google.com/mail/u/0/#inbox/FMfcgzQbfxQ",
+    priority: 2,
+    kind: "do",
+    meta: { thread_id: "FMfcgzQbfxQ", rule: "promised-reply" },
+};
+export const chooseCard = {
+    title: "Keep the Tuesday standup?",
+    body: "Attendance has been 3/7 for the last four weeks. Bryan asked twice whether it's still needed.",
+    source: { app: "Claude", context: "Calendar hygiene" },
+    priority: 4,
+    kind: "choose",
+    meta: { event_id: "standup-tue" },
+};
+export const checkinCard = {
+    title: "Still waiting on the Fly.io invoice from accounting?",
+    body: "Open since Oct 12. Last touch: you forwarded it to Priya on Oct 28.",
+    source: { app: "Claude", context: "Open loops" },
+    priority: 3,
+    kind: "checkin",
+    meta: { loop_id: "fly-invoice" },
+};
+export const decideCard = {
+    title: "Supabase or Vapor for the Ketch backend?",
+    body: "CLAUDE.md says Supabase by default. You've gone back and forth twice in Granola. Pick one and write it down.",
+    source: { app: "Claude", context: "Ketch architecture" },
+    link: "https://notes.granola.ai/d/4f1c2a",
+    priority: 2,
+    kind: "decide",
+    meta: { decision: "backend-stack" },
+};
+export const readCard = {
+    title: "Granola recap: Dosi-Smash weekly",
+    body: "- Shaina wants a reply on the marketing plan by Friday\n- Bryan owns the podcast outreach now\n- Next sync moved to Thursdays",
+    source: { app: "Claude", context: "Dosi-Smash weekly" },
+    link: "https://notes.granola.ai/d/9b2e77",
+    priority: 4,
+    kind: "read",
+    expires_at: "2026-11-12T07:00:00-08:00",
+};
+export const recapCard = {
+    title: "Anything else from today's Dosi-Smash call?",
+    body: "I captured: reply to Shaina, podcast outreach → Bryan. Add what I missed.",
+    source: { app: "Claude", context: "Dosi-Smash weekly" },
+    priority: 3,
+    kind: "recap",
+};
+/** Explicit actions override the preset; snooze_for sets the tap default. */
+export const customActionsCard = {
+    title: "Approve the $1,200 Zapier annual plan?",
+    body: "Renews Nov 9. Last year you used 14% of the task quota.",
+    source: { app: "Zapier", context: "Billing" },
+    link: "https://zapier.com/app/billing",
+    priority: 1,
+    kind: "decide",
+    actions: [
+        { id: "approve", label: "Approve", style: "positive" },
+        { id: "downgrade", label: "Downgrade", style: "neutral", input: "optional" },
+        { id: "later", label: "Ask me Monday", style: "snooze", snooze_for: "4d" },
+    ],
+    meta: { renewal_id: "zap-2026" },
+};
+/** Minimal: title only. Kind, actions, priority all come from defaults. */
+export const minimalCard = { title: "Call the dentist" };
+/** Email-in shape: subject = title, body = body, link = message. */
+export const emailInCard = {
+    title: "Fwd: Lease renewal paperwork",
+    body: "Hi Ev, attached is the renewal for 2027. Needs a signature by the 20th.",
+    source: { app: "Email", context: "landlord@example.com" },
+    link: "https://mail.google.com/mail/u/0/#inbox/18f3a2c",
+    kind: "do",
+};
+/** Hidden until the morning; a producer-side snooze. */
+export const scheduledCard = {
+    title: "Morning: review yesterday's not_good outcomes",
+    source: { app: "Claude", context: "Self-tuning" },
+    priority: 5,
+    kind: "read",
+    show_after: "2026-11-06T07:00:00-08:00",
+    recurrence: { every: "1d" },
+};
+export const byKind = {
+    do: doCard,
+    choose: chooseCard,
+    checkin: checkinCard,
+    decide: decideCard,
+    read: readCard,
+    recap: recapCard,
+};
+export const validCards = {
+    ...byKind,
+    customActions: customActionsCard,
+    minimal: minimalCard,
+    emailIn: emailInCard,
+    scheduled: scheduledCard,
+};
+/** Each must fail validateNewCard; `path` is the expected first error path. */
+export const invalidCards = {
+    missingTitle: { card: { body: "no title" }, path: "" },
+    emptyTitle: { card: { title: "" }, path: "/title" },
+    unknownField: { card: { title: "x", due: "tomorrow" }, path: "" },
+    unknownKind: { card: { title: "x", kind: "task" }, path: "/kind" },
+    priorityOutOfRange: { card: { title: "x", priority: 0 }, path: "/priority" },
+    httpLink: { card: { title: "x", link: "http://example.com" }, path: "/link" },
+    tooManyActions: {
+        card: { title: "x", actions: [{ id: "a", label: "A" }, { id: "b", label: "B" }, { id: "c", label: "C" }, { id: "d", label: "D" }, { id: "e", label: "E" }] },
+        path: "/actions",
+    },
+    noActions: { card: { title: "x", actions: [] }, path: "/actions" },
+    duplicateActionIds: { card: { title: "x", actions: [{ id: "a", label: "A" }, { id: "a", label: "Again" }] }, path: "/actions/1/id" },
+    badActionId: { card: { title: "x", actions: [{ id: "Done!", label: "Done" }] }, path: "/actions/0/id" },
+    badStyle: { card: { title: "x", actions: [{ id: "a", label: "A", style: "danger" }] }, path: "/actions/0/style" },
+    snoozeForOnNonSnooze: { card: { title: "x", actions: [{ id: "a", label: "A", style: "neutral", snooze_for: "1d" }] }, path: "/actions/0/snooze_for" },
+    badRecurrence: { card: { title: "x", recurrence: { every: "fortnight" } }, path: "/recurrence/every" },
+    badShowAfter: { card: { title: "x", show_after: "tomorrow 7am" }, path: "/show_after" },
+    metaNotObject: { card: { title: "x", meta: "notes" }, path: "/meta" },
+};

package/dist/src/duration.d.ts

@@ -0,0 +1,7 @@
+import type { Duration } from "./types.js";
+export declare const DURATION_RE: RegExp;
+export declare function isDuration(s: unknown): s is Duration;
+/** "14d" → milliseconds. Throws on a malformed duration. */
+export declare function durationToMs(d: Duration | string): number;
+/** now + duration, as an ISO string. */
+export declare function addDuration(from: Date, d: Duration | string): string;

package/dist/src/duration.js

@@ -0,0 +1,21 @@
+const UNIT_MS = {
+    m: 60_000,
+    h: 3_600_000,
+    d: 86_400_000,
+    w: 7 * 86_400_000,
+};
+export const DURATION_RE = /^([1-9][0-9]{0,4})([mhdw])$/;
+export function isDuration(s) {
+    return typeof s === "string" && DURATION_RE.test(s);
+}
+/** "14d" → milliseconds. Throws on a malformed duration. */
+export function durationToMs(d) {
+    const m = DURATION_RE.exec(d);
+    if (!m)
+        throw new Error(`Invalid duration: ${d}`);
+    return Number(m[1]) * UNIT_MS[m[2]];
+}
+/** now + duration, as an ISO string. */
+export function addDuration(from, d) {
+    return new Date(from.getTime() + durationToMs(d)).toISOString();
+}

package/dist/src/index.d.ts

@@ -0,0 +1,4 @@
+export * from "./types.js";
+export * from "./presets.js";
+export * from "./duration.js";
+export * from "./validate.js";

package/dist/src/index.js

@@ -0,0 +1,4 @@
+export * from "./types.js";
+export * from "./presets.js";
+export * from "./duration.js";
+export * from "./validate.js";

package/dist/src/presets.d.ts

@@ -0,0 +1,22 @@
+import type { Action, Input, Kind, NewCard, Recurrence } from "./types.js";
+/**
+ * Kind presets. A kind only fills in defaults the producer omitted; it never
+ * needs app code. Adding a kind = adding an entry here.
+ */
+export interface KindPreset {
+    actions: Action[];
+    recurrence?: Recurrence;
+    input?: Input;
+}
+export declare const KIND_PRESETS: Record<Kind, KindPreset>;
+export declare const DEFAULT_KIND: Kind;
+export declare const DEFAULT_PRIORITY: 3;
+/**
+ * Fill in everything the preset provides that the producer left out.
+ * Pure; returns a new object. Does not validate.
+ */
+export declare function withKindDefaults<T extends NewCard>(card: T): T & {
+    kind: Kind;
+    actions: Action[];
+    priority: number;
+};

package/dist/src/presets.js

@@ -0,0 +1,56 @@
+export const KIND_PRESETS = {
+    do: {
+        actions: [
+            { id: "done", label: "Done", style: "positive" },
+            { id: "snooze", label: "Snooze", style: "snooze" },
+            { id: "feedback", label: "Feedback", style: "neutral", input: "optional" },
+        ],
+    },
+    choose: {
+        actions: [
+            { id: "keep", label: "Keep", style: "positive" },
+            { id: "next", label: "Next", style: "neutral" },
+        ],
+    },
+    checkin: {
+        actions: [
+            { id: "still_true", label: "Still true", style: "positive" },
+            { id: "better", label: "Better", style: "neutral", input: "optional" },
+            { id: "resolved", label: "Resolved", style: "neutral" },
+        ],
+        recurrence: { every: "14d" },
+    },
+    decide: {
+        actions: [
+            { id: "decided", label: "Decided", style: "positive", input: "required" },
+            { id: "still_deciding", label: "Still deciding", style: "snooze", snooze_for: "3d" },
+        ],
+    },
+    read: {
+        actions: [{ id: "next", label: "Next", style: "positive" }],
+    },
+    recap: {
+        actions: [
+            { id: "nothing_more", label: "Nothing more", style: "positive" },
+            { id: "snooze", label: "Snooze", style: "snooze" },
+        ],
+        input: { placeholder: "Any other follow-ups?", spawns: true },
+    },
+};
+export const DEFAULT_KIND = "do";
+export const DEFAULT_PRIORITY = 3;
+/**
+ * Fill in everything the preset provides that the producer left out.
+ * Pure; returns a new object. Does not validate.
+ */
+export function withKindDefaults(card) {
+    const kind = card.kind ?? DEFAULT_KIND;
+    const preset = KIND_PRESETS[kind];
+    const out = { ...card, kind, priority: card.priority ?? DEFAULT_PRIORITY };
+    out.actions = (card.actions ?? preset.actions).map((a) => ({ style: "neutral", ...a }));
+    if (card.recurrence === undefined && preset.recurrence)
+        out.recurrence = { ...preset.recurrence };
+    if (card.input === undefined && preset.input)
+        out.input = { ...preset.input };
+    return out;
+}

package/dist/src/types.d.ts

@@ -0,0 +1,139 @@
+/**
+ * TypeScript mirror of card.schema.json. Keep the two in sync; the test
+ * `schema.test.ts` validates every fixture against the JSON Schema and the
+ * fixtures are typed with these types, so drift shows up at compile or test time.
+ */
+/** `<integer><unit>`; unit m | h | d | w. e.g. "1h", "3d", "14d". */
+export type Duration = `${number}${"m" | "h" | "d" | "w"}`;
+export type CardId = `card_${string}`;
+export type WebhookId = `wh_${string}`;
+export type ActionStyle = "positive" | "snooze" | "neutral";
+export type ActionInput = "optional" | "required";
+export interface Action {
+    /** Producer-chosen. `snooze` and `not_good` are reserved. */
+    id: string;
+    label: string;
+    /** default "neutral" */
+    style?: ActionStyle;
+    /** Open a text sheet before posting. */
+    input?: ActionInput;
+    /** Only meaningful for style "snooze": default snooze on tap (default 1h). */
+    snooze_for?: Duration;
+}
+export interface Source {
+    /** Defaults to the API key's name. */
+    app?: string;
+    context?: string;
+}
+export interface Input {
+    placeholder?: string;
+    /** Each entry becomes a new card (card.spawned). */
+    spawns?: boolean;
+}
+export interface Recurrence {
+    every: Duration;
+}
+export type Kind = "do" | "choose" | "checkin" | "decide" | "read" | "recap";
+export declare const KINDS: readonly Kind[];
+export type Priority = 1 | 2 | 3 | 4 | 5;
+export type Status = "open" | "snoozed" | "done";
+export type WebhookEvent = "card.acted" | "card.snoozed" | "card.spawned";
+export declare const WEBHOOK_EVENTS: readonly WebhookEvent[];
+/** Reserved action ids the app always offers in the overflow menu. */
+export declare const RESERVED_ACTION_IDS: readonly ["snooze", "not_good"];
+export type ReservedActionId = (typeof RESERVED_ACTION_IDS)[number];
+/** What a producer POSTs to /cards. */
+export interface NewCard {
+    title: string;
+    body?: string;
+    source?: Source;
+    link?: string;
+    priority?: Priority;
+    kind?: Kind;
+    actions?: Action[];
+    input?: Input;
+    recurrence?: Recurrence;
+    show_after?: string | null;
+    expires_at?: string | null;
+    meta?: Record<string, unknown>;
+}
+/** What PATCH /cards/:id accepts. */
+export interface CardPatch {
+    title?: string;
+    body?: string | null;
+    actions?: Action[];
+    show_after?: string | null;
+    priority?: Priority;
+    link?: string | null;
+    expires_at?: string | null;
+    meta?: Record<string, unknown>;
+}
+export interface Outcome {
+    action: string;
+    text: string | null;
+    at: string;
+    snoozed_until: string | null;
+}
+/** What the app POSTs to /cards/:id/outcome. */
+export interface OutcomeInput {
+    action: string;
+    text?: string | null;
+    snoozed_until?: string | null;
+    /** Titles of cards to spawn from the card's spawning input. */
+    spawn?: string[];
+}
+/** A card as the server returns it. */
+export interface Card {
+    id: CardId;
+    title: string;
+    body?: string;
+    source: {
+        app: string;
+        context?: string;
+    };
+    link?: string;
+    priority: Priority;
+    kind: Kind;
+    actions: Action[];
+    input?: Input;
+    recurrence?: Recurrence;
+    show_after?: string | null;
+    expires_at?: string | null;
+    meta?: Record<string, unknown>;
+    status: Status;
+    parent_id?: CardId | null;
+    outcome?: Outcome | null;
+    created_at: string;
+    updated_at: string;
+    retired_at?: string | null;
+}
+export interface NewWebhook {
+    url: string;
+    secret: string;
+    events: WebhookEvent[];
+}
+export interface Webhook {
+    id: WebhookId;
+    url: string;
+    events: WebhookEvent[];
+    created_at: string;
+}
+export type WebhookPayload = {
+    id: string;
+    event: "card.acted";
+    at: string;
+    card: Card;
+    outcome: Outcome;
+} | {
+    id: string;
+    event: "card.snoozed";
+    at: string;
+    card: Card;
+    outcome: Outcome;
+} | {
+    id: string;
+    event: "card.spawned";
+    at: string;
+    parent: Card;
+    card: Card;
+};

package/dist/src/types.js

@@ -0,0 +1,9 @@
+/**
+ * TypeScript mirror of card.schema.json. Keep the two in sync; the test
+ * `schema.test.ts` validates every fixture against the JSON Schema and the
+ * fixtures are typed with these types, so drift shows up at compile or test time.
+ */
+export const KINDS = ["do", "choose", "checkin", "decide", "read", "recap"];
+export const WEBHOOK_EVENTS = ["card.acted", "card.snoozed", "card.spawned"];
+/** Reserved action ids the app always offers in the overflow menu. */
+export const RESERVED_ACTION_IDS = ["snooze", "not_good"];