@waler/sdk 0.1.1

package/dist/types.d.ts

@@ -0,0 +1,324 @@
+/**
+ * The public surface of `@waler/sdk`.
+ *
+ * These declarations are additive: fields are added, never repurposed. An app
+ * built against an older version of this package keeps working against a newer
+ * shell, which is the guarantee the whole design rests on.
+ */
+/** Where the app is running. `standalone` means it is outside a shell. */
+export type Platform = 'web' | 'ios' | 'android' | 'standalone';
+/**
+ * Which population a user belongs to. One shell serves all of them, and a
+ * surface declares which ones it is for.
+ *
+ * It is derived from what the user actually has access to, never assigned
+ * directly, so an app can read it but never change it.
+ */
+export type Audience = 'buyer' | 'staff' | 'broker';
+/**
+ * The context the shell resolved for this surface.
+ *
+ * `tenantId`, `userId`, `audiences` and `activeAudience` are always present.
+ * Every other field is present only when the surface declared that it needs it,
+ * so check before use.
+ */
+export interface ShellContext {
+    tenantId: string;
+    userId: string;
+    /**
+     * Every population this user belongs to. It can hold more than one, so never
+     * assume a single element and never read `audiences[0]` as "the" audience.
+     */
+    audiences: readonly Audience[];
+    /**
+     * The population the shell is rendering under right now, and the one to branch
+     * on. `audiences` says what the user could switch to; this says what they are
+     * looking at. It always belongs to `audiences`, and it can change without a
+     * reload — listen for `audiencechange`.
+     */
+    activeAudience: Audience;
+    ventureId?: string;
+    buildingId?: string;
+    unitId?: string;
+    salesContractId?: string;
+    partyId?: string;
+}
+/** Theme tokens for the current tenant, so an app can match the surrounding UI. */
+export interface ThemeTokens {
+    colorScheme: 'light' | 'dark';
+    primary: string;
+    onPrimary: string;
+    surface: string;
+    onSurface: string;
+    border: string;
+    danger: string;
+    radius: string;
+    fontFamily: string;
+    /** Extra tokens a tenant may define. Always treat them as optional. */
+    [token: string]: string;
+}
+/**
+ * Capabilities a shell may offer. The list grows over time, so `Capability`
+ * accepts any string: never break on seeing a name you do not recognise.
+ */
+export type KnownCapability = 'download' | 'notify' | 'share' | 'camera' | 'scanBarcode' | 'geolocation' | 'biometrics' | 'haptics' | 'clipboard' | 'openExternal' | 'requestReview';
+export type Capability = KnownCapability | (string & {});
+export interface CapabilitySet {
+    /** Check support with this, never by comparing versions. */
+    has(capability: Capability): boolean;
+    list(): readonly Capability[];
+}
+/**
+ * Where to reach the platform API for this tenant and environment.
+ *
+ * Never hardcode these. One build of an app runs inside many shells on different
+ * domains and across environments; only the shell knows which one this is.
+ */
+export interface PlatformEndpoints {
+    /** Root of the platform API. Build request URLs from this. */
+    baseUrl: string;
+    /**
+     * Issuer of the tokens `getToken()` returns. Your backend validates them by
+     * discovering the JWKS from here, instead of shipping a key in its code.
+     */
+    issuer: string;
+}
+/** Resolved when the handshake with the shell finishes. */
+export interface ReadyPayload {
+    /** Version of the host shell. For telemetry only — gate on `capabilities`. */
+    shellVersion: string;
+    sdkVersion: string;
+    platform: Platform;
+    /** Where to reach the platform API. Never hardcode it. */
+    api: PlatformEndpoints;
+    capabilities: readonly Capability[];
+    locale: string;
+    timeZone: string;
+    theme: ThemeTokens;
+    context: ShellContext;
+}
+export type KnownSdkErrorCode = 
+/** The shell does not offer this method or capability. Take your fallback path. */
+'UNSUPPORTED'
+/** Not granted to this app, or denied for this user. */
+ | 'FORBIDDEN'
+/** The user backed out, or denied a permission. */
+ | 'CANCELLED' | 'TIMEOUT' | 'INVALID_ARGUMENT'
+/** The app is running outside a shell. */
+ | 'NOT_IN_SHELL' | 'INTERNAL';
+/**
+ * An OPEN union, for the same reason `Capability` is open: the shell moves ahead
+ * of the SDK. A shell that learns a new code
+ * would have it collapsed into `INTERNAL` by a closed union, and the app would
+ * lose the one piece of information that could have told it what happened —
+ * silently, and only in the tenants that had already updated.
+ *
+ * `if (e.code === 'UNSUPPORTED')` keeps working unchanged. What this costs is
+ * that an exhaustive `switch` now needs a `default`, which it needed anyway.
+ */
+export type SdkErrorCode = KnownSdkErrorCode | (string & {});
+export interface SdkError extends Error {
+    readonly code: SdkErrorCode;
+    readonly method?: string;
+    readonly details?: unknown;
+}
+export interface TokenRequest {
+    /** Who the token is for. Omit it for your own backend. */
+    audience?: string;
+    scopes?: readonly string[];
+    /** Skip the cache and request a freshly issued token. */
+    forceRefresh?: boolean;
+}
+export interface TokenResult {
+    token: string;
+    expiresAt: string;
+    scopes: readonly string[];
+}
+export interface SdkEventMap {
+    /** The shell resolved a different context, without reloading the surface. */
+    contextchange: ShellContext;
+    /** The user switched populations. Only fires for users who have more than one. */
+    audiencechange: {
+        activeAudience: Audience;
+        audiences: readonly Audience[];
+    };
+    /**
+     * The result of a write this app started, which completes asynchronously.
+     *
+     * Assume both: it MAY NOT ARRIVE, so rebuild state when your view opens; and it
+     * MAY ARRIVE TWICE, so handle it idempotently by `commandId`.
+     */
+    commandupdate: {
+        commandId: string;
+        status: 'dispatched' | 'confirmed' | 'failed' | 'compensated';
+        error?: {
+            code: string;
+            message: string;
+        };
+    };
+    themechange: ThemeTokens;
+    localechange: {
+        locale: string;
+        timeZone: string;
+    };
+    /** The surface left or came back to the screen. Pause background work when hidden. */
+    visibilitychange: {
+        visible: boolean;
+    };
+    /** Early warning that the current token is about to expire. Call `getToken()`. */
+    tokenexpiring: {
+        expiresAt: string;
+    };
+}
+export type Unsubscribe = () => void;
+export interface NotifyOptions {
+    /** A notification channel this app declared. */
+    channel: string;
+    title: string;
+    body?: string;
+    /** Which surface to open when the notification is tapped. */
+    deepLink?: {
+        key: string;
+        params?: Record<string, string>;
+    };
+}
+export interface DownloadOptions {
+    url: string;
+    filename: string;
+    mimeType?: string;
+}
+export interface ShareOptions {
+    title?: string;
+    text?: string;
+    url?: string;
+}
+export interface ScanResult {
+    value: string;
+    format: string;
+}
+export interface GeolocationResult {
+    latitude: number;
+    longitude: number;
+    accuracy: number;
+    capturedAt: string;
+}
+export interface HeaderState {
+    title?: string;
+    /** Badge count shown on this app inside the shell. */
+    badge?: number;
+    /** Hide the shell's header for a full-bleed screen. */
+    hidden?: boolean;
+}
+export interface WalerSDK {
+    /**
+     * Resolves when the handshake with the shell completes, and only over a live
+     * bridge with a payload the SDK has already checked — so after `await ready`,
+     * `context` is filled and `capabilities` is populated.
+     *
+     * Rejects with `NOT_IN_SHELL` when there is no shell, and with `FORBIDDEN` when
+     * the shell refuses this surface. It never resolves half-way.
+     */
+    readonly ready: Promise<ReadyPayload>;
+    /**
+     * Null until `ready` resolves, then kept in step with `contextchange` and
+     * `audiencechange`. Prefer `const { context } = await Waler.ready`, which has
+     * no null in it; this is for code that runs later and cannot await.
+     */
+    readonly context: ShellContext | null;
+    readonly capabilities: CapabilitySet;
+    getToken(request?: TokenRequest): Promise<TokenResult>;
+    /**
+     * Opens another surface — this app's or another installed app's — and resolves
+     * with whatever that surface passed to `close(result)`. Allow for it taking as
+     * long as a person takes.
+     */
+    openApp<T = void>(key: string, params?: Record<string, string>): Promise<T>;
+    /**
+     * Tells the shell your current route, for deep links and the back button.
+     *
+     * Call it yourself: the SDK does not watch `history.pushState` to infer it,
+     * because patching a global inside your app would fight whatever your router
+     * does to the same function.
+     */
+    navigate(path: string): void;
+    /** Closes this surface. `result` resolves the `openApp()` that opened it. */
+    close(result?: unknown): void;
+    /** Sets the title, badge or visibility of the shell's header for this surface. */
+    setHeader(state: HeaderState): void;
+    notify(options: NotifyOptions): Promise<void>;
+    download(options: DownloadOptions): Promise<void>;
+    share(options: ShareOptions): Promise<void>;
+    scanBarcode(): Promise<ScanResult>;
+    getGeolocation(): Promise<GeolocationResult>;
+    on<K extends keyof SdkEventMap>(event: K, handler: (payload: SdkEventMap[K]) => void): Unsubscribe;
+    /**
+     * Typed escape hatch for methods newer than this package. Rejects with
+     * `UNSUPPORTED` if the shell does not know the method.
+     */
+    invoke<T = unknown>(method: string, payload?: unknown): Promise<T>;
+}
+/**
+ * Options for `createSdk`.
+ *
+ * Nothing is installed on `window` and nothing happens on import; if you want a
+ * global, assign one yourself: `window.Waler = createSdk({ … })`.
+ */
+export interface WalerSdkOptions {
+    /** This app's registered id, sent in the handshake. */
+    readonly appId: string;
+    /**
+     * The shell origins this surface accepts, and the only ones it will ever post
+     * to. Anything that is not an absolute `http(s)` origin is dropped, so no
+     * wildcard can be expressed — `'*'` would deliver to whatever page embedded
+     * the app, permitted or not.
+     *
+     * If nothing usable is left, `ready` rejects with `INVALID_ARGUMENT` rather
+     * than silently reaching nobody.
+     */
+    readonly allowedOrigins: readonly string[];
+}
+/**
+ * The envelope every message travels in. `v` is the protocol's version — not
+ * the shell's and not this package's — and it only moves on a breaking change to
+ * the protocol itself.
+ */
+export interface BridgeEnvelope {
+    v: 1;
+    /** Pairs one request with its response. */
+    id: string;
+    /**
+     * Identifies a whole user action, across every hop it causes. Where `id` pairs
+     * two messages, this stays the same for everything one action sets off, so a
+     * single failure can be traced through every system that handled it.
+     */
+    correlationId: string;
+    kind: 'request' | 'response' | 'error' | 'event';
+    method?: string;
+    /**
+     * A `string` rather than the closed set of known event names: a shell newer
+     * than this package can send names it cannot enumerate. Unknown names find no
+     * handler and are dropped.
+     */
+    event?: string;
+    payload?: unknown;
+    error?: {
+        code: SdkErrorCode;
+        message: string;
+        details?: unknown;
+    };
+}
+/**
+ * The contract every transport implements. The SDK picks one for the platform it
+ * finds itself on, and an app never sees the difference.
+ *
+ * Note what is NOT here: no origin, no target window, no serialisation. Those
+ * belong to whichever transport needs them, so this interface stays
+ * implementable everywhere the SDK runs.
+ */
+export interface BridgeTransport {
+    readonly platform: Platform;
+    send(envelope: BridgeEnvelope): void;
+    onMessage(handler: (envelope: BridgeEnvelope) => void): Unsubscribe;
+    /** `false` on the null transport — the app is outside the shell. */
+    readonly connected: boolean;
+}

package/dist/types.js

@@ -0,0 +1,8 @@
+/**
+ * The public surface of `@waler/sdk`.
+ *
+ * These declarations are additive: fields are added, never repurposed. An app
+ * built against an older version of this package keeps working against a newer
+ * shell, which is the guarantee the whole design rests on.
+ */
+export {};

package/dist/version.d.ts

@@ -0,0 +1,2 @@
+/** Kept in step with package.json by `pnpm version-packages`. */
+export declare const SDK_VERSION = "0.1.1";

package/dist/version.js

@@ -0,0 +1,2 @@
+/** Kept in step with package.json by `pnpm version-packages`. */
+export const SDK_VERSION = '0.1.1';

package/package.json

@@ -0,0 +1,68 @@
+{
+  "name": "@waler/sdk",
+  "version": "0.1.1",
+  "description": "The surface a Waler app talks to the shell through.",
+  "license": "MIT",
+  "keywords": [
+    "waler",
+    "sdk",
+    "micro-frontend",
+    "iframe",
+    "postmessage",
+    "bridge",
+    "superapp"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/waler-app/waler-sdk.git"
+  },
+  "homepage": "https://github.com/waler-app/waler-sdk#readme",
+  "bugs": "https://github.com/waler-app/waler-sdk/issues",
+  "type": "module",
+  "sideEffects": false,
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "dist"
+  ],
+  "engines": {
+    "node": ">=20"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "devDependencies": {
+    "@arethetypeswrong/cli": "^0.18.5",
+    "@changesets/cli": "^3.0.1",
+    "@commitlint/cli": "^21.2.2",
+    "@commitlint/config-conventional": "^21.2.2",
+    "@eslint/js": "^10.0.1",
+    "@types/node": "^26.4.0",
+    "eslint": "^10.9.1",
+    "eslint-config-prettier": "^10.1.8",
+    "prettier": "^3.9.6",
+    "publint": "^0.3.24",
+    "typescript": "^6.0.3",
+    "typescript-eslint": "^8.68.0"
+  },
+  "scripts": {
+    "build": "node -e \"fs.rmSync('dist',{recursive:true,force:true})\" && tsc -p tsconfig.build.json",
+    "typecheck": "tsc --noEmit -p tsconfig.json",
+    "lint": "eslint .",
+    "lint:fix": "eslint . --fix",
+    "format": "prettier --write .",
+    "format:check": "prettier --check .",
+    "test": "node --test test/*.test.ts",
+    "check:origins": "pnpm build && node tools/origin-check/serve.ts",
+    "check:package": "pnpm build && publint && attw --pack . --profile esm-only",
+    "verify:tarball": "node tools/verify-tarball.ts",
+    "changeset": "changeset",
+    "version-packages": "changeset version && node tools/sync-version.ts && prettier --write package.json CHANGELOG.md src/version.ts",
+    "release": "pnpm check:package && changeset publish"
+  }
+}