@wyndlass/app-sdk 0.0.0 → 1.1.0

package/dist/contract/app-definition.d.ts

@@ -0,0 +1,155 @@
+export type CommonSemver = string;
+/**
+ * BCP 47 language tag.
+ */
+export type CommonLocale = string;
+/**
+ * The YAML definition of a web component app (scoping doc 7.8). Drives the designer's property panel, the catalog and the MCP tools.
+ */
+export interface AppDefinition {
+    /**
+     * Reverse-domain id, e.g. com.wyndlass.weather. com.wyndlass. is Wyndlass's own: an app an organization imports may not use it (WP-0100).
+     */
+    id: string;
+    version: CommonSemver;
+    name: string;
+    description?: string;
+    /**
+     * The element's name. From Player API 2 (WP-0100) the host defines the module's default export under this name, a hyphen and a suffix of its own, so it is the readable part of the tag. Wyndlass's apps also define it themselves, for players older than that.
+     */
+    element: string;
+    params?: {
+        [k: string]: Param | undefined;
+    };
+    properties?: {
+        resizable?: boolean;
+        minDuration?: string;
+        offline?: boolean;
+        transparent?: boolean;
+        aspectRatio?: string;
+    };
+    capabilities?: {
+        network?: string[];
+        /**
+         * Sensors the app reads on the screen. `impressions`: the live, anonymous feed of the people at the screen, where its site measures them (WP-0105): context.impressions.
+         */
+        sensors?: string[];
+        audio?: boolean;
+        peers?: boolean;
+        /**
+         * What the app may do with the player's controller (ADR 0050): read its properties and events (read, the default), or also command playback, audio and display (control). The CMS shows it when the app is added.
+         */
+        player?: "read" | "control";
+    };
+    bindings?: string[];
+    /**
+     * Named binding slots (ADR 0053, decision 8; DES-AP-01): each a field the app shows, mapped to a table column in a layout's binding. A layout's binding.fields names these.
+     */
+    slots?: {
+        [k: string]: {
+            label: string;
+            /**
+             * What the column must hold.
+             */
+            type: "text" | "number" | "currency" | "date" | "datetime" | "image" | "url" | "boolean";
+            required?: boolean;
+            help?: string;
+        } | undefined;
+    };
+    /**
+     * The presets the app's enter and exit hooks take (ADR 0053, decision 8; DES-AH-01 to 07). An app without them is animated as one box.
+     */
+    animation?: {
+        /**
+         * Presets its enter hook plays (fade, slide, typewriter...).
+         */
+        enter?: string[];
+        /**
+         * Presets its exit hook plays.
+         */
+        exit?: string[];
+        /**
+         * Its items can enter one after another (DES-AN-06).
+         */
+        stagger?: boolean;
+        /**
+         * It pages through its items, playing exit and enter at each page (DES-DB-13): its page count comes from the snapshot the layout started with.
+         */
+        pages?: boolean;
+    };
+    /**
+     * The data service's sources it reads (ADR 0069): weather, news.
+     */
+    data?: string[];
+    events?: {
+        emits?: string[];
+        consumes?: string[];
+    };
+    mobile?: {
+        mode?: "render" | "snapshot" | "hidden";
+    };
+    locales?: CommonLocale[];
+}
+export interface Param {
+    /**
+     * A param's kind. A font param's value is a typography object (layout.schema.json#/$defs/typography): a family with its weight, style, decoration, letter case and spacing, line height, shadow and scale.
+     */
+    type: "string" | "text" | "number" | "boolean" | "enum" | "color" | "font" | "media" | "location" | "datetime" | "duration" | "url" | "datatable" | "column" | "secret" | "json";
+    label?: string;
+    default?: unknown;
+    /**
+     * On an enum, its choices. On any other type, suggestions the designer offers, while any valid value is still allowed (WP-0098). Each is a plain value, or labeled: shown by its label, under its group.
+     *
+     * @minItems 1
+     */
+    values?: [ParamValue, ...ParamValue[]];
+    group?: string;
+    required?: boolean;
+    min?: number;
+    max?: number;
+    step?: number;
+    help?: string;
+    advanced?: boolean;
+    /**
+     * When the param applies (WP-0068 part f, after gadget.yaml's depends): each key names another param of this app, and its test must hold. A param that does not apply is not shown in the designer and is not required; its value is kept.
+     */
+    when?: {
+        [k: string]: ParamTest | undefined;
+    };
+}
+/**
+ * A value as a param's values list it (WP-0098): a string, number or boolean, or labeled ({ value, label, group }) for the designer to show by its label, under its group.
+ */
+export interface ParamValue {
+    [k: string]: unknown | undefined;
+}
+/**
+ * A test of another param's value (WP-0068 part f): every one given must hold. Values compare as text.
+ */
+export interface ParamTest {
+    /**
+     * Its value is one of these.
+     *
+     * @minItems 1
+     * @maxItems 50
+     */
+    anyOf?: [string | number | boolean, ...(string | number | boolean)[]];
+    /**
+     * Its value, a list, holds every one of these.
+     *
+     * @minItems 1
+     * @maxItems 50
+     */
+    allOf?: [string | number | boolean, ...(string | number | boolean)[]];
+    /**
+     * Its value is none of these.
+     *
+     * @minItems 1
+     * @maxItems 50
+     */
+    noneOf?: [string | number | boolean, ...(string | number | boolean)[]];
+    /**
+     * true: it has a value; false: it has none (absent, empty text, or an empty list).
+     */
+    set?: boolean;
+}

package/dist/contract/app-definition.js

@@ -0,0 +1,3 @@
+// Copied from protocol/generated/ts/app-definition.d.ts by app-sdk/scripts/copy-protocol.mjs: edit the source, then run `pnpm --filter @wyndlass/app-sdk copy-protocol`.
+/* Generated from protocol/schemas by scripts/generate.mjs. Do not edit. */
+export {};

package/dist/contract/data-answer.d.ts

@@ -0,0 +1,40 @@
+/**
+ * What the data service answers for any source (ADR 0069): GET /v0/{source}. data is the source's normalized form (data-weather, data-news, data-quotes, data-series, data-calendar). Players keep the last answer and show it offline with its age.
+ */
+export interface DataServiceAnswer {
+    /**
+     * The source asked: weather, news, quotes, series, calendar.
+     */
+    source: string;
+    /**
+     * The parameters the answer is for, as the service normalized them (a place rounded to 0.1°, a feed's URL). A calendar's address is left out: it often works as a password (WP-0111).
+     */
+    params: {
+        [k: string]: (string | number | boolean) | undefined;
+    };
+    /**
+     * When the provider answered.
+     */
+    fetchedAt: string;
+    /**
+     * When to ask again.
+     */
+    expiresAt: string;
+    /**
+     * True when the provider failed and this is the last answer it gave, kept for up to a day past expiresAt.
+     */
+    stale: boolean;
+    /**
+     * Credit the source requires wherever its data is shown (Open-Meteo: CC BY 4.0).
+     */
+    attribution?: {
+        text: string;
+        url?: string;
+    };
+    /**
+     * The source's normalized data.
+     */
+    data: {
+        [k: string]: unknown | undefined;
+    };
+}

package/dist/contract/data-answer.js

@@ -0,0 +1,3 @@
+// Copied from protocol/generated/ts/data-answer.d.ts by app-sdk/scripts/copy-protocol.mjs: edit the source, then run `pnpm --filter @wyndlass/app-sdk copy-protocol`.
+/* Generated from protocol/schemas by scripts/generate.mjs. Do not edit. */
+export {};

package/dist/contract/data-calendar.d.ts

@@ -0,0 +1,57 @@
+/**
+ * An instant in UTC (2026-10-14T14:00:00Z); a date (2026-10-14) for a whole-day event; a local time (2026-10-14T09:00:00) for a floating one.
+ */
+export type Time = string;
+/**
+ * The data service's calendar from an iCalendar, jCal or xCal feed (ADR 0069, WP-0111): the occurrences in the window asked for, repeats and time zones worked out, in time order. Attendees, organizers, alarms and attachments are never carried; a private event has no title, place or description.
+ */
+export interface Calendar {
+    calendar: {
+        /**
+         * X-WR-CALNAME, or NAME (RFC 7986).
+         */
+        name?: string;
+        /**
+         * X-WR-TIMEZONE, as the calendar gives it.
+         */
+        timeZone?: string;
+    };
+    /**
+     * @maxItems 1000
+     */
+    events: {
+        /**
+         * The event's UID; for a repeat or a changed occurrence, the UID and the occurrence's start (20261014T140000Z).
+         */
+        id: string;
+        title?: string;
+        location?: string;
+        /**
+         * Plain text: markup stripped.
+         */
+        description?: string;
+        start: Time;
+        end: Time;
+        /**
+         * A whole-day event: start and end are dates, the end exclusive.
+         */
+        allDay?: true;
+        /**
+         * A floating event: start and end are local times with no zone, read in the screen's time zone.
+         */
+        floating?: true;
+        tentative?: true;
+        /**
+         * TRANSP:TRANSPARENT: the event does not make its calendar busy.
+         */
+        free?: true;
+        /**
+         * CLASS:PRIVATE or CONFIDENTIAL: its title, place and description are left out.
+         */
+        private?: true;
+    }[];
+    /**
+     * The window held more than 1,000 occurrences: the ones nearest the time asked are kept.
+     */
+    truncated?: true;
+}

package/dist/contract/data-calendar.js

@@ -0,0 +1,3 @@
+// Copied from protocol/generated/ts/data-calendar.d.ts by app-sdk/scripts/copy-protocol.mjs: edit the source, then run `pnpm --filter @wyndlass/app-sdk copy-protocol`.
+/* Generated from protocol/schemas by scripts/generate.mjs. Do not edit. */
+export {};

package/dist/contract/data-news.d.ts

@@ -0,0 +1,29 @@
+/**
+ * The data service's news from an RSS 2.0 or Atom 1.0 feed (ADR 0069), each item's image its own or its page's Open Graph image.
+ */
+export interface News {
+    feed: {
+        title: string;
+        url: string;
+        link?: string;
+        image?: string;
+    };
+    /**
+     * @maxItems 50
+     */
+    items: {
+        id?: string;
+        title: string;
+        /**
+         * Plain text: markup stripped.
+         */
+        summary?: string;
+        link: string;
+        published?: string;
+        author?: string;
+        /**
+         * The item's image through the data service's image proxy (a path from the service's root), so screens load only from Wyndlass.
+         */
+        image?: string;
+    }[];
+}

package/dist/contract/data-news.js

@@ -0,0 +1,3 @@
+// Copied from protocol/generated/ts/data-news.d.ts by app-sdk/scripts/copy-protocol.mjs: edit the source, then run `pnpm --filter @wyndlass/app-sdk copy-protocol`.
+/* Generated from protocol/schemas by scripts/generate.mjs. Do not edit. */
+export {};

package/dist/contract/data-quotes.d.ts

@@ -0,0 +1,75 @@
+/**
+ * Why a symbol has no answer: the provider does not know it, the plan does not cover it, or there is no answer and no earlier one.
+ */
+export type Reason = "unknown-symbol" | "not-in-plan" | "unavailable";
+/**
+ * The data service's quotes from Twelve Data (ADR 0069, decision 9; WP-0103): each symbol asked for, in the order asked, or why it is missing. A value the provider does not give is left out.
+ */
+export interface Quotes {
+    /**
+     * @maxItems 30
+     */
+    quotes: {
+        /**
+         * The symbol as asked, upper-cased: AAPL, EUR/USD, or with its exchange after a colon (TRP:TSX).
+         */
+        symbol: string;
+        name?: string;
+        exchange?: string;
+        /**
+         * The exchange's market identifier code (ISO 10383).
+         */
+        mic?: string;
+        /**
+         * The price's currency, where the provider gives one (not for currency pairs or crypto).
+         */
+        currency?: string;
+        /**
+         * The latest price.
+         */
+        price: number;
+        /**
+         * The price less the previous close.
+         */
+        change?: number;
+        /**
+         * The change as a percentage of the previous close.
+         */
+        percentChange?: number;
+        open?: number;
+        high?: number;
+        low?: number;
+        previousClose?: number;
+        /**
+         * Shares traded today, where there are shares.
+         */
+        volume?: number;
+        averageVolume?: number;
+        fiftyTwoWeek?: {
+            low: number;
+            high: number;
+        };
+        /**
+         * Whether its market is open now.
+         */
+        marketOpen: boolean;
+        /**
+         * When the price was quoted.
+         */
+        time: string;
+        /**
+         * True when the provider failed and this is the symbol's last quote, kept for up to a day.
+         */
+        stale: boolean;
+    }[];
+    /**
+     * @maxItems 30
+     */
+    missing: {
+        /**
+         * The symbol as asked, upper-cased: AAPL, EUR/USD, or with its exchange after a colon (TRP:TSX).
+         */
+        symbol: string;
+        reason: Reason;
+    }[];
+}

package/dist/contract/data-quotes.js

@@ -0,0 +1,3 @@
+// Copied from protocol/generated/ts/data-quotes.d.ts by app-sdk/scripts/copy-protocol.mjs: edit the source, then run `pnpm --filter @wyndlass/app-sdk copy-protocol`.
+/* Generated from protocol/schemas by scripts/generate.mjs. Do not edit. */
+export {};

package/dist/contract/data-series.d.ts

@@ -0,0 +1,51 @@
+/**
+ * The data service's prices for one symbol over a range, from Twelve Data (ADR 0069, decision 9; WP-0103), for charts: the bars oldest first, or why the symbol is missing. A value the provider does not give is left out.
+ */
+export interface Series {
+    /**
+     * The symbol as asked, upper-cased: AAPL, EUR/USD, or with its exchange after a colon (TRP:TSX).
+     */
+    symbol: string;
+    /**
+     * 1d: the latest trading day in 5-minute bars (the last 24 hours where a market never closes); 5d: 30-minute bars; 1m, 6m and 1y: days; 5y: weeks.
+     */
+    range: "1d" | "5d" | "1m" | "6m" | "1y" | "5y";
+    interval?: "5min" | "30min" | "1day" | "1week";
+    exchange?: string;
+    mic?: string;
+    currency?: string;
+    /**
+     * The provider's kind of instrument: Common Stock, ETF, Physical Currency, Digital Currency.
+     */
+    type?: string;
+    /**
+     * The exchange's time zone (IANA), which a trading day is counted in.
+     */
+    timeZone?: string;
+    /**
+     * For 1d and 5d: whether the market is open now, as its last bar is recent.
+     */
+    marketOpen?: boolean;
+    /**
+     * For 1d: the close before the day's first bar, which the day's change is measured from.
+     */
+    previousClose?: number;
+    /**
+     * @maxItems 400
+     */
+    points?: {
+        /**
+         * The bar's start.
+         */
+        time: string;
+        open: number;
+        high: number;
+        low: number;
+        close: number;
+        volume?: number;
+    }[];
+    /**
+     * Why a symbol has no answer: the provider does not know it, the plan does not cover it, or there is no answer and no earlier one.
+     */
+    missing?: "unknown-symbol" | "not-in-plan" | "unavailable";
+}

package/dist/contract/data-series.js

@@ -0,0 +1,3 @@
+// Copied from protocol/generated/ts/data-series.d.ts by app-sdk/scripts/copy-protocol.mjs: edit the source, then run `pnpm --filter @wyndlass/app-sdk copy-protocol`.
+/* Generated from protocol/schemas by scripts/generate.mjs. Do not edit. */
+export {};

package/dist/contract/data-snapshot.d.ts

@@ -0,0 +1,30 @@
+/**
+ * A column's key: set when the column is added and never changed, so a binding to it survives a relabel.
+ */
+export type Key = string;
+/**
+ * One version of a data table as screens read it (WP-0072, ADR 0072; ADR 0053 decision 7): a content-addressed JSON blob the manifest's dataSnapshots name. Bindings address a cell by its row's position in rows and its column's key. Values are typed: numbers as numbers, booleans as booleans, dates and date-times as ISO text; an empty cell is left out.
+ */
+export interface DataTableSnapshot {
+    /**
+     * The table's id, as the manifest's dataSnapshots names it.
+     */
+    table: string;
+    version: number;
+    /**
+     * @minItems 1
+     * @maxItems 50
+     */
+    columns: [Column, ...Column[]];
+    /**
+     * @maxItems 5000
+     */
+    rows: {
+        [k: string]: (string | number | boolean) | undefined;
+    }[];
+}
+export interface Column {
+    key: Key;
+    label: string;
+    type: "text" | "number" | "currency" | "date" | "datetime" | "url" | "boolean";
+}

package/dist/contract/data-snapshot.js

@@ -0,0 +1,3 @@
+// Copied from protocol/generated/ts/data-snapshot.d.ts by app-sdk/scripts/copy-protocol.mjs: edit the source, then run `pnpm --filter @wyndlass/app-sdk copy-protocol`.
+/* Generated from protocol/schemas by scripts/generate.mjs. Do not edit. */
+export {};