@tula-tech/contract 0.0.0-stage → 0.1.0-alpha.1

package/dist/theme.d.ts

@@ -0,0 +1,227 @@
+/**
+* The theme tokens every Tula front end shares: names, types and default values for light and
+* dark.
+*
+* This module is plain data and pure functions with no dependency (no Zod), so `@tula-tech/react`
+* loads it at run time from `@tula-tech/contract/theme`, and the Swift and Kotlin SDKs generate
+* their constants from the same table. Everything here is JSON-serialisable on purpose: a
+* theme can be written in `tula.config.ts`, stored by the dashboard's editor, or read by a
+* code generator in another language.
+*
+* Tokens are append-only, like error codes: removing or renaming one is a breaking change for
+* every app that sets it.
+*/
+/**
+* The tokens that differ between light and dark: colours and the card's shadow.
+*
+* Colours are `#rrggbb`, or on the web any form {@link isValidThemeValue} accepts (hex,
+* `rgb()`-style functions, keywords); the defaults are all `#rrggbb` so that every platform can parse them and their contrast can be checked.
+*/
+interface ThemeScheme {
+	/** Behind a component: the card, the menu, the dialog. */
+	background: string;
+	/** A quieter panel on top of the background: list rows, the hover state of a menu item. */
+	surface: string;
+	/** The inside of a text field. */
+	input: string;
+	/** Body text and headings. */
+	text: string;
+	/** Secondary text: hints, descriptions, an unmet checklist rule. */
+	textMuted: string;
+	/** The brand colour: the main button, the selected state. */
+	primary: string;
+	/** The main button while hovered or pressed. */
+	primaryHover: string;
+	/** Text and icons on top of `primary`. */
+	primaryText: string;
+	/** Links and text buttons. */
+	link: string;
+	/** Hairlines: the card's edge, dividers. */
+	border: string;
+	/** The edge of a control (a text field, a secondary button). At least 3:1 on `background`. */
+	borderStrong: string;
+	/** Error text, the edge of an invalid field, destructive actions. */
+	danger: string;
+	/** Behind an error message. */
+	dangerSurface: string;
+	/** A met checklist rule, a success message. */
+	success: string;
+	/** The keyboard focus ring. At least 3:1 on `background`. */
+	focus: string;
+	/** Dims the page behind a dialog. */
+	overlay: string;
+	/** The card's shadow (a CSS `box-shadow` value; other platforms map it to an elevation). */
+	shadow: string;
+}
+/**
+* A complete theme: one {@link ThemeScheme} for light, one for dark, and the tokens both share.
+*
+* @example
+* ```ts
+* const theme: Theme = { ...DEFAULT_THEME, radius: '6px' }
+* ```
+*/
+interface Theme {
+	/** Colours and shadow in the light scheme. */
+	light: ThemeScheme;
+	/** Colours and shadow in the dark scheme. */
+	dark: ThemeScheme;
+	/** Corner radius of cards, fields and buttons. */
+	radius: string;
+	/** Corner radius of small parts: badges, menu items, the checklist bar. */
+	radiusSmall: string;
+	/** The typeface of everything. */
+	fontFamily: string;
+	/** The typeface of codes and keys. */
+	fontFamilyMono: string;
+	/** Body text size. */
+	fontSize: string;
+	/** Size of hints, badges and the checklist. */
+	fontSizeSmall: string;
+	/** Size of a card's title. */
+	fontSizeTitle: string;
+	/** The spacing unit: gaps and paddings are multiples of it. */
+	spacing: string;
+}
+/**
+* Part of a theme: only the tokens an app wants to change. What it leaves out keeps the
+* default. Values are validated before use (see {@link isValidThemeValue}): one that is not a
+* plain colour, length, font list or shadow is dropped and the default stays.
+*
+* @example
+* ```ts
+* const brand: ThemeOverrides = {
+*   light: { primary: '#0f766e', primaryHover: '#115e59' },
+*   dark: { primary: '#5eead4', primaryText: '#042f2e' },
+*   radius: '6px',
+* }
+* ```
+*/
+type ThemeOverrides = Partial<Omit<Theme, "light" | "dark">> & {
+	/** Tokens to change in the light scheme. */
+	light?: Partial<ThemeScheme>;
+	/** Tokens to change in the dark scheme. */
+	dark?: Partial<ThemeScheme>;
+};
+/** What kind of value a token holds, for a generator that has to map it to a platform type. */
+type ThemeTokenType = "color" | "shadow" | "length" | "fontFamily";
+/** One token of the theme, described for code generators and documentation. */
+interface ThemeTokenDefinition {
+	/** The token's key in {@link ThemeScheme} (`scope: 'scheme'`) or {@link Theme} (`'shared'`). */
+	readonly key: string;
+	/** `scheme`: a value per colour scheme. `shared`: one value for both. */
+	readonly scope: "scheme" | "shared";
+	/** The kind of value. */
+	readonly type: ThemeTokenType;
+	/**
+	* The CSS custom property an app sets to change the token (in the light scheme, for a
+	* `scheme` token). A `scheme` token's dark value is set with {@link darkCssVariable}.
+	*/
+	readonly cssVariable: `--tula-${string}`;
+	/** What the token is used for. */
+	readonly description: string;
+}
+/**
+* Every token, in the order stylesheets and generated constants list them.
+*
+* @example
+* ```ts
+* for (const token of THEME_TOKENS) {
+*   // token.key 'primary', token.cssVariable '--tula-color-primary', token.type 'color'
+* }
+* ```
+*/
+declare const THEME_TOKENS: readonly ThemeTokenDefinition[];
+/**
+* The default theme. Every text colour has a contrast of at least 4.5:1 on the backgrounds it
+* is drawn on, and control edges and the focus ring at least 3:1, in both schemes (WCAG 2.2
+* AA); the contract's tests compute it.
+*
+* @example
+* ```ts
+* DEFAULT_THEME.light.primary // '#5b4cf0'
+* ```
+*/
+declare const DEFAULT_THEME: Theme;
+/**
+* The CSS custom property that sets a `scheme` token's value in the dark scheme.
+*
+* Light and dark have separate properties so that an app can set both in one place (a
+* stylesheet rule or an inline style) without a media query.
+*
+* @param cssVariable - The token's `cssVariable`.
+* @returns The dark property's name.
+*
+* @example
+* ```ts
+* darkCssVariable('--tula-color-primary') // '--tula-dark-color-primary'
+* ```
+*/
+declare function darkCssVariable(cssVariable: `--tula-${string}`): `--tula-dark-${string}`;
+/**
+* Whether a string is a plain value of a token's type, safe to write into a stylesheet or a
+* `style` attribute.
+*
+* Theme values are **untrusted**: a brand colour can come from a database a tenant edits, and
+* a server-rendered theme is written into the page as text, where `red; background: url(…)`
+* would become a second declaration. So a value is not escaped, it is checked against a strict
+* grammar for its type and dropped when it does not match:
+*
+* - `color`: `#rgb`, `#rgba`, `#rrggbb`, `#rrggbbaa`; `rgb()`, `rgba()`, `hsl()`, `hsla()`,
+*   `hwb()`, `lab()`, `lch()`, `oklab()`, `oklch()` with plain numeric arguments; or a colour
+*   keyword (letters only).
+* - `length`: `0`, or a number with one of `px rem em % ch ex pt vw vh vmin vmax`.
+* - `fontFamily`: a comma-separated list of quoted names or bare words.
+* - `shadow`: `none`, or comma-separated layers of an optional `inset`, two to four lengths
+*   and at most one colour.
+*
+* Whatever the type, nothing longer than 200 characters and nothing containing `;` `{` `}`
+* `<` `>` `\` `@` `!`, a line break, a comment opener, `url(`, `expression(` or `var(` passes.
+*
+* @param type - The token's type.
+* @param value - The candidate value.
+* @returns `true` when the value may be used.
+*
+* @example
+* ```ts
+* isValidThemeValue('color', '#0f766e') // true
+* isValidThemeValue('color', 'red; background: url(https://evil.example/x)') // false
+* ```
+*/
+declare function isValidThemeValue(type: ThemeTokenType, value: string): boolean;
+/**
+* Turn a theme, or part of one, into CSS custom properties.
+*
+* Only the tokens present in `theme` are returned, so the result of a partial theme can be
+* applied as an inline style on top of the stylesheet's defaults. Unknown keys are ignored,
+* and so is any value that {@link isValidThemeValue} refuses: theme values are untrusted (they
+* may come from tenant-editable data) and are never written out unless they are a plain value
+* of their token's type.
+* Light values use each token's `cssVariable`; dark values its {@link darkCssVariable}.
+*
+* @param theme - A theme or overrides.
+* @returns Property names and values, in the order of {@link THEME_TOKENS}.
+*
+* @example
+* ```ts
+* themeToCssVariables({ light: { primary: '#0f766e' }, dark: { primary: '#5eead4' }, radius: '6px' })
+* // { '--tula-color-primary': '#0f766e', '--tula-dark-color-primary': '#5eead4', '--tula-radius': '6px' }
+* ```
+*/
+declare function themeToCssVariables(theme: ThemeOverrides): Record<string, string>;
+/**
+* The WCAG contrast ratio of two opaque colours, from 1 (the same colour) to 21 (black on
+* white). Body text needs 4.5; large text, control edges and focus rings need 3.
+*
+* @param foreground - A `#rrggbb` colour.
+* @param background - A `#rrggbb` colour.
+* @returns The ratio.
+* @throws TypeError for a colour that is not `#rrggbb`.
+*
+* @example
+* ```ts
+* contrastRatio('#ffffff', '#5b4cf0') >= 4.5 // white text on the default primary passes AA
+* ```
+*/
+declare function contrastRatio(foreground: string, background: string): number;
+export { DEFAULT_THEME, THEME_TOKENS, Theme, ThemeOverrides, ThemeScheme, ThemeTokenDefinition, ThemeTokenType, contrastRatio, darkCssVariable, isValidThemeValue, themeToCssVariables };

package/dist/theme.js

@@ -0,0 +1,16 @@
+import {
+  THEME_TOKENS2,
+  DEFAULT_THEME2,
+  darkCssVariable2,
+  isValidThemeValue2,
+  themeToCssVariables2,
+  contrastRatio2
+} from "./shared/chunk-pcn6ax54.js";
+export {
+  DEFAULT_THEME2 as DEFAULT_THEME,
+  THEME_TOKENS2 as THEME_TOKENS,
+  contrastRatio2 as contrastRatio,
+  darkCssVariable2 as darkCssVariable,
+  isValidThemeValue2 as isValidThemeValue,
+  themeToCssVariables2 as themeToCssVariables
+};

package/dist/webhook-signature.d.ts

@@ -0,0 +1,103 @@
+/**
+* Request header carrying the delivery's id: the event's id. A delivery that is repeated
+* carries the same id, so a receiver drops duplicates by it.
+*
+* @example
+* ```ts
+* const id = request.headers.get(WEBHOOK_ID_HEADER)
+* ```
+*/
+declare const WEBHOOK_ID_HEADER = "webhook-id";
+/**
+* Request header carrying when the delivery was sent, in whole seconds since the Unix epoch.
+* It is signed, and a receiver refuses one too far from its own clock.
+*
+* @example
+* ```ts
+* const sentAt = Number(request.headers.get(WEBHOOK_TIMESTAMP_HEADER)) * 1000
+* ```
+*/
+declare const WEBHOOK_TIMESTAMP_HEADER = "webhook-timestamp";
+/**
+* Request header carrying the signatures: one or more of `v1,<base64>`, separated by spaces.
+* A receiver accepts the delivery when any one of them is right.
+*
+* @example
+* ```ts
+* const signatures = (request.headers.get(WEBHOOK_SIGNATURE_HEADER) ?? '').split(' ')
+* ```
+*/
+declare const WEBHOOK_SIGNATURE_HEADER = "webhook-signature";
+/**
+* What an endpoint's signing secret starts with. The rest is the base64 of the key's bytes.
+*
+* @example
+* ```ts
+* secret.startsWith(WEBHOOK_SECRET_PREFIX) // 'whsec_…'
+* ```
+*/
+declare const WEBHOOK_SECRET_PREFIX = "whsec_";
+/**
+* The version label of an HMAC-SHA256 signature: what stands before the comma.
+*
+* @example
+* ```ts
+* const [version, signature] = entry.split(',') // version === WEBHOOK_SIGNATURE_VERSION
+* ```
+*/
+declare const WEBHOOK_SIGNATURE_VERSION = "v1";
+/**
+* How far a delivery's timestamp may be from the receiver's clock, either way, in seconds.
+* Five minutes: what bounds the replay of a captured delivery.
+*
+* @example
+* ```ts
+* const fresh = Math.abs(now - sentAt) <= WEBHOOK_TOLERANCE_SECONDS
+* ```
+*/
+declare const WEBHOOK_TOLERANCE_SECONDS: number;
+/**
+* The key bytes of a signing secret.
+*
+* @param secret - An endpoint's secret: `whsec_` and the base64 of 24 to 64 bytes.
+* @returns The bytes, or `null` for anything else. Never throws, and says nothing of the value.
+*
+* @example
+* ```ts
+* const key = webhookSecretBytes(process.env.TULA_WEBHOOK_SECRET ?? '')
+* ```
+*/
+declare function webhookSecretBytes(secret: string): Uint8Array<ArrayBuffer> | null;
+/**
+* Write a signing secret from its key bytes.
+*
+* @param key - 24 to 64 random bytes.
+* @returns `whsec_` and the base64 of the bytes.
+* @throws RangeError when the key is shorter or longer than the scheme allows.
+*
+* @example
+* ```ts
+* const secret = formatWebhookSecret(crypto.getRandomValues(new Uint8Array(32)))
+* ```
+*/
+declare function formatWebhookSecret(key: Uint8Array): string;
+/**
+* Sign one delivery: HMAC-SHA256 over `<id>.<timestamp>.<body>`, keyed with the secret's bytes.
+*
+* The body is the exact text that is sent. A receiver must verify the bytes it received, not
+* a body it parsed and wrote out again.
+*
+* @param key - The key bytes ({@link webhookSecretBytes}).
+* @param id - The delivery's id (the `webhook-id` header). It has no `.` in it.
+* @param timestamp - Whole seconds since the Unix epoch (the `webhook-timestamp` header).
+* @param body - The request body, as sent.
+* @returns The signature as it stands in the header: `v1,<base64>`.
+*
+* @example
+* ```ts
+* const signature = await signWebhook(key, event.id, Math.floor(Date.now() / 1000), body)
+* // 'v1,g0hM9SsE+OTPJTGt/tmIKtSyZlE3uFJELVlNIOLJ1OE='
+* ```
+*/
+declare function signWebhook(key: Uint8Array<ArrayBuffer>, id: string, timestamp: number, body: string): Promise<string>;
+export { WEBHOOK_ID_HEADER, WEBHOOK_SECRET_PREFIX, WEBHOOK_SIGNATURE_HEADER, WEBHOOK_SIGNATURE_VERSION, WEBHOOK_TIMESTAMP_HEADER, WEBHOOK_TOLERANCE_SECONDS, formatWebhookSecret, signWebhook, webhookSecretBytes };

package/dist/webhook-signature.js

@@ -0,0 +1,22 @@
+import {
+  WEBHOOK_ID_HEADER2,
+  WEBHOOK_TIMESTAMP_HEADER2,
+  WEBHOOK_SIGNATURE_HEADER2,
+  WEBHOOK_SECRET_PREFIX2,
+  WEBHOOK_SIGNATURE_VERSION2,
+  WEBHOOK_TOLERANCE_SECONDS2,
+  webhookSecretBytes2,
+  formatWebhookSecret2,
+  signWebhook2
+} from "./shared/chunk-2xak18qy.js";
+export {
+  WEBHOOK_ID_HEADER2 as WEBHOOK_ID_HEADER,
+  WEBHOOK_SECRET_PREFIX2 as WEBHOOK_SECRET_PREFIX,
+  WEBHOOK_SIGNATURE_HEADER2 as WEBHOOK_SIGNATURE_HEADER,
+  WEBHOOK_SIGNATURE_VERSION2 as WEBHOOK_SIGNATURE_VERSION,
+  WEBHOOK_TIMESTAMP_HEADER2 as WEBHOOK_TIMESTAMP_HEADER,
+  WEBHOOK_TOLERANCE_SECONDS2 as WEBHOOK_TOLERANCE_SECONDS,
+  formatWebhookSecret2 as formatWebhookSecret,
+  signWebhook2 as signWebhook,
+  webhookSecretBytes2 as webhookSecretBytes
+};