npm - @ketch.to/schema - Versions diffs - 0.0.0-stage → 0.1.0 - Mend

@ketch.to/schema 0.0.0-stage → 0.1.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (16) hide show

package/README.md CHANGED Viewed

@@ -1,3 +1,12 @@
-# Temporary Holding Version
+# @ketch.to/schema
-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.
+The card schema for [Ketch](https://ketch.to): JSON Schema (draft 2020-12), TypeScript types, validators and kind presets.
+```ts
+import { validateNewCard, withKindDefaults, type NewCard } from "@ketch.to/schema";
+const result = validateNewCard({ title: "Reply to Shaina's marketing plan", kind: "do" });
+if (!result.ok) console.error(result.errors);
+```
+The raw schema is exported as `@ketch.to/schema/card.schema.json`, and example cards for every kind as `@ketch.to/schema/fixtures`.

package/card.schema.json ADDED Viewed

@@ -0,0 +1,601 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://ketch.to/schemas/card.json",
+  "title": "Ketch card schema",
+  "description": "The one data structure in Ketch. A card is a question an agent asks a person; it has exactly one outcome.",
+  "$defs": {
+    "Duration": {
+      "type": "string",
+      "description": "Relative duration: <integer><unit>, unit one of m (minutes), h (hours), d (days), w (weeks).",
+      "pattern": "^[1-9][0-9]{0,4}[mhdw]$",
+      "examples": [
+        "1h",
+        "3d",
+        "14d",
+        "2w"
+      ]
+    },
+    "CardId": {
+      "type": "string",
+      "pattern": "^card_[0-9A-HJKMNP-TV-Z]{26}$",
+      "description": "Server-assigned. 'card_' + ULID."
+    },
+    "ActionId": {
+      "type": "string",
+      "pattern": "^[a-z][a-z0-9_]{0,31}$",
+      "description": "Producer-chosen id, echoed back in the outcome. 'snooze' and 'not_good' are reserved and always available."
+    },
+    "ActionStyle": {
+      "type": "string",
+      "enum": [
+        "positive",
+        "snooze",
+        "neutral"
+      ],
+      "description": "positive: swipe-right target, accent colour. snooze: tap = 1h, hold = day slider. neutral: plain button."
+    },
+    "Action": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "id",
+        "label"
+      ],
+      "properties": {
+        "id": {
+          "$ref": "#/$defs/ActionId"
+        },
+        "label": {
+          "type": "string",
+          "minLength": 1,
+          "maxLength": 24
+        },
+        "style": {
+          "$ref": "#/$defs/ActionStyle",
+          "default": "neutral"
+        },
+        "input": {
+          "type": "string",
+          "enum": [
+            "optional",
+            "required"
+          ],
+          "description": "Open a text sheet before posting this action."
+        },
+        "snooze_for": {
+          "$ref": "#/$defs/Duration",
+          "description": "Only for style 'snooze': the default snooze on tap. Defaults to 1h."
+        }
+      }
+    },
+    "Actions": {
+      "type": "array",
+      "minItems": 1,
+      "maxItems": 4,
+      "items": {
+        "$ref": "#/$defs/Action"
+      }
+    },
+    "Source": {
+      "type": "object",
+      "additionalProperties": false,
+      "properties": {
+        "app": {
+          "type": "string",
+          "minLength": 1,
+          "maxLength": 40,
+          "description": "Defaults to the API key's name."
+        },
+        "context": {
+          "type": "string",
+          "minLength": 1,
+          "maxLength": 120
+        }
+      }
+    },
+    "Input": {
+      "type": "object",
+      "additionalProperties": false,
+      "properties": {
+        "placeholder": {
+          "type": "string",
+          "maxLength": 80
+        },
+        "spawns": {
+          "type": "boolean",
+          "default": false,
+          "description": "Each entry the person types becomes a new card (event card.spawned)."
+        }
+      }
+    },
+    "Recurrence": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "every"
+      ],
+      "properties": {
+        "every": {
+          "$ref": "#/$defs/Duration"
+        }
+      }
+    },
+    "Kind": {
+      "type": "string",
+      "enum": [
+        "do",
+        "choose",
+        "checkin",
+        "decide",
+        "read",
+        "recap"
+      ],
+      "description": "Preset. Fills in default actions (and recurrence/input for some) when the producer omits them. Never requires app code."
+    },
+    "Priority": {
+      "type": "integer",
+      "minimum": 1,
+      "maximum": 5,
+      "default": 3,
+      "description": "1 urgent … 5 ambient. ≤2 pushes a notification."
+    },
+    "Link": {
+      "type": "string",
+      "pattern": "^(https://|shortcuts://)[^\\s]+$",
+      "maxLength": 2048,
+      "description": "Opened with the system. https:// or shortcuts:// only."
+    },
+    "Meta": {
+      "type": "object",
+      "description": "Producer's own bag. Echoed back untouched in webhooks and outcomes."
+    },
+    "CardFields": {
+      "type": "object",
+      "properties": {
+        "title": {
+          "type": "string",
+          "minLength": 1,
+          "maxLength": 140
+        },
+        "body": {
+          "type": "string",
+          "maxLength": 4000,
+          "description": "Plain text or light markdown."
+        },
+        "source": {
+          "$ref": "#/$defs/Source"
+        },
+        "link": {
+          "$ref": "#/$defs/Link"
+        },
+        "priority": {
+          "$ref": "#/$defs/Priority"
+        },
+        "kind": {
+          "$ref": "#/$defs/Kind",
+          "default": "do"
+        },
+        "actions": {
+          "$ref": "#/$defs/Actions"
+        },
+        "input": {
+          "$ref": "#/$defs/Input"
+        },
+        "recurrence": {
+          "$ref": "#/$defs/Recurrence"
+        },
+        "show_after": {
+          "type": [
+            "string",
+            "null"
+          ],
+          "format": "date-time",
+          "description": "Hidden until then. Snooze writes this."
+        },
+        "expires_at": {
+          "type": [
+            "string",
+            "null"
+          ],
+          "format": "date-time",
+          "description": "Retired automatically with outcome action 'expired'."
+        },
+        "meta": {
+          "$ref": "#/$defs/Meta"
+        }
+      }
+    },
+    "NewCard": {
+      "description": "What a producer POSTs. Everything but title is optional; kind fills in actions.",
+      "allOf": [
+        {
+          "$ref": "#/$defs/CardFields"
+        }
+      ],
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "title"
+      ],
+      "properties": {
+        "title": true,
+        "body": true,
+        "source": true,
+        "link": true,
+        "priority": true,
+        "kind": true,
+        "actions": true,
+        "input": true,
+        "recurrence": true,
+        "show_after": true,
+        "expires_at": true,
+        "meta": true
+      }
+    },
+    "CardPatch": {
+      "description": "What PATCH /cards/:id accepts. Producer-side edits only.",
+      "type": "object",
+      "additionalProperties": false,
+      "minProperties": 1,
+      "properties": {
+        "title": {
+          "type": "string",
+          "minLength": 1,
+          "maxLength": 140
+        },
+        "body": {
+          "type": [
+            "string",
+            "null"
+          ],
+          "maxLength": 4000
+        },
+        "actions": {
+          "$ref": "#/$defs/Actions"
+        },
+        "show_after": {
+          "type": [
+            "string",
+            "null"
+          ],
+          "format": "date-time"
+        },
+        "priority": {
+          "$ref": "#/$defs/Priority"
+        },
+        "link": {
+          "anyOf": [
+            {
+              "$ref": "#/$defs/Link"
+            },
+            {
+              "type": "null"
+            }
+          ]
+        },
+        "expires_at": {
+          "type": [
+            "string",
+            "null"
+          ],
+          "format": "date-time"
+        },
+        "meta": {
+          "$ref": "#/$defs/Meta"
+        }
+      }
+    },
+    "Status": {
+      "type": "string",
+      "enum": [
+        "open",
+        "snoozed",
+        "done"
+      ],
+      "description": "open: in the queue. snoozed: open but show_after is in the future. done: retired (acted, deleted or expired)."
+    },
+    "Outcome": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "action",
+        "text",
+        "at",
+        "snoozed_until"
+      ],
+      "properties": {
+        "action": {
+          "$ref": "#/$defs/ActionId"
+        },
+        "text": {
+          "type": [
+            "string",
+            "null"
+          ],
+          "maxLength": 4000
+        },
+        "at": {
+          "type": "string",
+          "format": "date-time"
+        },
+        "snoozed_until": {
+          "type": [
+            "string",
+            "null"
+          ],
+          "format": "date-time"
+        }
+      }
+    },
+    "OutcomeInput": {
+      "description": "What the app POSTs to /cards/:id/outcome. One per card (snoozes excepted).",
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "action"
+      ],
+      "properties": {
+        "action": {
+          "$ref": "#/$defs/ActionId"
+        },
+        "text": {
+          "type": [
+            "string",
+            "null"
+          ],
+          "maxLength": 4000
+        },
+        "snoozed_until": {
+          "type": [
+            "string",
+            "null"
+          ],
+          "format": "date-time",
+          "description": "Required when action is 'snooze' (or any snooze-style action)."
+        },
+        "spawn": {
+          "type": "array",
+          "maxItems": 20,
+          "items": {
+            "type": "string",
+            "minLength": 1,
+            "maxLength": 140
+          },
+          "description": "Titles of new cards to create from the card's spawning input."
+        }
+      }
+    },
+    "Card": {
+      "description": "A card as the server returns it.",
+      "allOf": [
+        {
+          "$ref": "#/$defs/CardFields"
+        }
+      ],
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "id",
+        "title",
+        "source",
+        "priority",
+        "kind",
+        "actions",
+        "status",
+        "created_at",
+        "updated_at"
+      ],
+      "properties": {
+        "id": {
+          "$ref": "#/$defs/CardId"
+        },
+        "title": true,
+        "body": true,
+        "link": true,
+        "priority": true,
+        "kind": true,
+        "actions": true,
+        "input": true,
+        "recurrence": true,
+        "show_after": true,
+        "expires_at": true,
+        "meta": true,
+        "source": {
+          "type": "object",
+          "additionalProperties": false,
+          "required": [
+            "app"
+          ],
+          "properties": {
+            "app": {
+              "type": "string",
+              "minLength": 1,
+              "maxLength": 40
+            },
+            "context": {
+              "type": "string",
+              "minLength": 1,
+              "maxLength": 120
+            }
+          }
+        },
+        "status": {
+          "$ref": "#/$defs/Status"
+        },
+        "parent_id": {
+          "anyOf": [
+            {
+              "$ref": "#/$defs/CardId"
+            },
+            {
+              "type": "null"
+            }
+          ],
+          "description": "Set on cards spawned from another card's input."
+        },
+        "outcome": {
+          "anyOf": [
+            {
+              "$ref": "#/$defs/Outcome"
+            },
+            {
+              "type": "null"
+            }
+          ],
+          "description": "The last outcome, if any. Recurring cards keep their latest."
+        },
+        "created_at": {
+          "type": "string",
+          "format": "date-time"
+        },
+        "updated_at": {
+          "type": "string",
+          "format": "date-time"
+        },
+        "retired_at": {
+          "type": [
+            "string",
+            "null"
+          ],
+          "format": "date-time"
+        }
+      }
+    },
+    "WebhookEvent": {
+      "type": "string",
+      "enum": [
+        "card.acted",
+        "card.snoozed",
+        "card.spawned"
+      ]
+    },
+    "NewWebhook": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "url",
+        "secret",
+        "events"
+      ],
+      "properties": {
+        "url": {
+          "type": "string",
+          "pattern": "^https?://[^\\s]+$",
+          "maxLength": 2048
+        },
+        "secret": {
+          "type": "string",
+          "minLength": 16,
+          "maxLength": 256
+        },
+        "events": {
+          "type": "array",
+          "minItems": 1,
+          "uniqueItems": true,
+          "items": {
+            "$ref": "#/$defs/WebhookEvent"
+          }
+        }
+      }
+    },
+    "Webhook": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "id",
+        "url",
+        "events",
+        "created_at"
+      ],
+      "properties": {
+        "id": {
+          "type": "string",
+          "pattern": "^wh_[0-9A-HJKMNP-TV-Z]{26}$"
+        },
+        "url": {
+          "type": "string"
+        },
+        "events": {
+          "type": "array",
+          "items": {
+            "$ref": "#/$defs/WebhookEvent"
+          }
+        },
+        "created_at": {
+          "type": "string",
+          "format": "date-time"
+        }
+      }
+    },
+    "WebhookPayload": {
+      "description": "Body of every webhook POST. HMAC-SHA256 hex of the raw body, keyed with the webhook secret, in X-Ketch-Signature.",
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "id",
+        "event",
+        "at"
+      ],
+      "properties": {
+        "id": {
+          "type": "string",
+          "description": "Delivery id. Same id on every retry; use it to dedupe."
+        },
+        "event": {
+          "$ref": "#/$defs/WebhookEvent"
+        },
+        "at": {
+          "type": "string",
+          "format": "date-time"
+        },
+        "card": {
+          "$ref": "#/$defs/Card"
+        },
+        "outcome": {
+          "$ref": "#/$defs/Outcome"
+        },
+        "parent": {
+          "$ref": "#/$defs/Card"
+        }
+      },
+      "oneOf": [
+        {
+          "properties": {
+            "event": {
+              "const": "card.acted"
+            },
+            "parent": false
+          },
+          "required": [
+            "card",
+            "outcome"
+          ]
+        },
+        {
+          "properties": {
+            "event": {
+              "const": "card.snoozed"
+            },
+            "parent": false
+          },
+          "required": [
+            "card",
+            "outcome"
+          ]
+        },
+        {
+          "properties": {
+            "event": {
+              "const": "card.spawned"
+            },
+            "outcome": false
+          },
+          "required": [
+            "parent",
+            "card"
+          ]
+        }
+      ]
+    }
+  }
+}