@checkcourt/sdk 0.3.1 → 0.4.0

package/README.md

@@ -21,18 +21,11 @@ Cloudflare Workers, Vercel Edge or Deno. Its only runtime dependency is `openapi
 
 ## Install
 
-The package is not on npm yet. Until it is, install a tagged release straight from GitHub:
-
 ```bash
-npm install github:CheckCourt/sdk#v0.3.1
+npm install @checkcourt/sdk
 ```
 
-npm builds the package on install. Once it is published, the package name will be
-`@checkcourt/sdk`:
-
-```bash
-npm install @checkcourt/sdk   # coming soon
-```
+Every release is also tagged on [GitHub](https://github.com/CheckCourt/sdk/releases).
 
 ## Quick start
 
@@ -122,6 +115,17 @@ export async function POST(request: Request) {
 }
 ```
 
+CheckCourt keeps a successful render for 30 seconds. Pass `maxAge` (seconds, at most 300,
+sent as `cache.max_age`) to change that for one answer, or `0` when the panel must always
+be fresh:
+
+```ts
+return Response.json(ui.doc([ui.stat("Battery", `${level} %`)], { maxAge: 0 }));
+```
+
+A `Cache-Control` response header (`no-store`, `max-age=N`) works too; `maxAge` wins when
+both are set. In your sandbox club nothing is cached.
+
 Compare `context.installation_id` and `context.tenant_id` with what you stored from
 `app.installed` before you act on a request. For the context token alone (for example in
 the backend of an iframe extension), use `verifyExtensionContext(token, secret)`.
@@ -192,7 +196,7 @@ Full guides and the API reference: <https://docs.checkcourt.de/docs/developer/sd
 ## Versioning
 
 The SDK follows semantic versioning but is still in `0.x`: minor releases may contain
-breaking changes until 1.0. Pin a tag and read the [changelog](CHANGELOG.md) before you
+breaking changes until 1.0. Pin a version and read the [changelog](CHANGELOG.md) before you
 upgrade.
 
 The exported constant `OPENAPI_SPEC_SHA256` is the SHA-256 of the spec the bundled types
@@ -226,6 +230,16 @@ CHECKCOURT_OPENAPI=./openapi.json npm run generate  # a local file or another UR
 The generated types follow the platform. A release may ship types for endpoints that are
 about to be deployed, so do not regenerate them in an unrelated pull request.
 
+### Releasing
+
+1. Bump `version` in `package.json` (`npm version <x.y.z> --no-git-tag-version`).
+2. Add the release to `CHANGELOG.md`.
+3. Run `npm run build` and commit, including the rebuilt `dist/`.
+4. Tag the commit `vX.Y.Z` and push the tag (`git push origin vX.Y.Z`).
+
+The release workflow checks that the tag matches the package version and that `dist/` is
+up to date, then publishes to npm with provenance via trusted publishing.
+
 ## License
 
 [MIT](LICENSE)

package/dist/ui.d.ts

@@ -112,17 +112,28 @@ export type UiToast = {
     kind: "success" | "error";
     message: string;
 };
-/** The response of a declarative extension: `{ ui: "v1", blocks, toast? }`. */
+/** CheckCourt caps every render lifetime at this many seconds. */
+export declare const UI_CACHE_MAX_AGE_LIMIT = 300;
+/**
+ * How long CheckCourt may reuse a render, in whole seconds. `0` means never. Without it
+ * CheckCourt follows the response's `Cache-Control` header, else keeps a render for 30 seconds.
+ */
+export type UiCache = {
+    max_age: number;
+};
+/** The response of a declarative extension: `{ ui: "v1", blocks, toast?, cache? }`. */
 export interface UiDocument {
     ui: typeof UI_VERSION;
     blocks: UiBlock[];
     toast?: UiToast;
+    cache?: UiCache;
 }
 /** Tells CheckCourt to show no card for this subject and viewer; on an action, removes the panel. */
 export interface UiHiddenDocument {
     ui: typeof UI_VERSION;
     hidden: true;
     toast?: UiToast;
+    cache?: UiCache;
 }
 /** Anything a declarative extension may answer with. */
 export type UiResponse = UiDocument | UiHiddenDocument;
@@ -131,18 +142,20 @@ export type UiFormValues = Record<string, string | number | boolean>;
 type Opt<T> = {
     [K in keyof T]?: T[K];
 };
+/** Options shared by `ui.doc` and `ui.hidden`. */
+export interface UiDocumentOptions {
+    toast?: UiToast;
+    /** Seconds CheckCourt may reuse this render, sent as `cache.max_age`; `0` disables caching. Capped at 300. */
+    maxAge?: number;
+}
 /**
  * Builds `ui: "v1"` documents. Strings are plain text (no HTML, no Markdown); CheckCourt
  * renders them with its own design system.
  */
 export declare const ui: {
-    readonly doc: (blocks: UiBlock[], options?: {
-        toast?: UiToast;
-    }) => UiDocument;
+    readonly doc: (blocks: UiBlock[], options?: UiDocumentOptions) => UiDocument;
     /** Nothing relevant here: no card at all. Answering `204 No Content` does the same. */
-    readonly hidden: (options?: {
-        toast?: UiToast;
-    }) => UiHiddenDocument;
+    readonly hidden: (options?: UiDocumentOptions) => UiHiddenDocument;
     readonly text: (text: string, options?: {
         tone?: "muted";
     }) => UiTextBlock;

package/dist/ui.js

@@ -4,6 +4,8 @@ export const MAX_UI_BLOCKS = 50;
 export const MAX_UI_DEPTH = 3;
 export const BADGE_VARIANTS = ["default", "secondary", "outline", "destructive"];
 export const BUTTON_VARIANTS = ["default", "secondary", "outline", "destructive"];
+/** CheckCourt caps every render lifetime at this many seconds. */
+export const UI_CACHE_MAX_AGE_LIMIT = 300;
 const field = {
     text(name, label, options = {}) {
         return { type: "text", name, label, ...options };
@@ -21,17 +23,25 @@ const field = {
 function compact(value) {
     return Object.fromEntries(Object.entries(value).filter(([, v]) => v !== undefined));
 }
+function cacheOf(maxAge) {
+    if (maxAge === undefined)
+        return undefined;
+    if (!Number.isInteger(maxAge) || maxAge < 0) {
+        throw new RangeError(`maxAge must be a whole number of seconds >= 0, got ${maxAge}`);
+    }
+    return { max_age: maxAge };
+}
 /**
  * Builds `ui: "v1"` documents. Strings are plain text (no HTML, no Markdown); CheckCourt
  * renders them with its own design system.
  */
 export const ui = {
     doc(blocks, options = {}) {
-        return compact({ ui: UI_VERSION, blocks, toast: options.toast });
+        return compact({ ui: UI_VERSION, blocks, toast: options.toast, cache: cacheOf(options.maxAge) });
     },
     /** Nothing relevant here: no card at all. Answering `204 No Content` does the same. */
     hidden(options = {}) {
-        return compact({ ui: UI_VERSION, hidden: true, toast: options.toast });
+        return compact({ ui: UI_VERSION, hidden: true, toast: options.toast, cache: cacheOf(options.maxAge) });
     },
     text(text, options = {}) {
         return compact({ type: "text", text, tone: options.tone });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@checkcourt/sdk",
-  "version": "0.3.1",
+  "version": "0.4.0",
   "description": "Official TypeScript SDK for the CheckCourt app platform",
   "private": false,
   "license": "MIT",