@stardeck-customer-apps/controls 0.0.0-stage → 0.3.0

package/dist/server/index.cjs

@@ -0,0 +1,436 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/server/index.ts
+var index_exports = {};
+__export(index_exports, {
+  createControlsClient: () => createControlsClient,
+  getControl: () => getControl,
+  getControls: () => getControls,
+  refreshControls: () => refreshControls,
+  resetControlsState: () => resetControlsState,
+  setControl: () => setControl,
+  setUsageProvider: () => setUsageProvider
+});
+module.exports = __toCommonJS(index_exports);
+
+// src/controls.ts
+var import_zod = require("zod");
+var CONTROLS = {
+  "flag.paymentsSetupStep": { schema: import_zod.z.boolean(), appWrite: false },
+  "plan.locations": {
+    schema: import_zod.z.object({
+      /** Locations the plan includes. null = agreed per deal. */
+      included: import_zod.z.number().int().positive().nullable(),
+      /** Hard cap. Platform plan: 1; others: null (no cap, extras are billed). */
+      max: import_zod.z.number().int().positive().nullable(),
+      /** Monthly price of each location past `included`. null = not offered. */
+      extraMonthly: import_zod.z.object({
+        amount: import_zod.z.number().nonnegative(),
+        currency: import_zod.z.enum(["THB", "USD"])
+      }).nullable()
+    }),
+    appWrite: false
+  },
+  "plan.multiEntity": { schema: import_zod.z.boolean(), appWrite: false },
+  "payments.provider": { schema: import_zod.z.enum(["beam", "stripe"]).nullable(), appWrite: true },
+  "payments.methods": {
+    schema: import_zod.z.object({ card: import_zod.z.boolean(), promptPay: import_zod.z.boolean() }),
+    appWrite: true
+  },
+  "pos.pro": {
+    schema: import_zod.z.object({
+      /** POS Pro locations paid for. null = unlimited (legacy plans, internal orgs). */
+      locations: import_zod.z.number().int().nonnegative().nullable()
+    }),
+    appWrite: false
+  },
+  /**
+   * The Accounting Module edition the org pays for, each an add-on next to its plan. null means
+   * no Accounting plan: the app has no Accounting. `{ ok: false }` means unknown right now:
+   * refuse new accounting records and keep existing ones readable.
+   */
+  "plan.accountingEdition": {
+    schema: import_zod.z.enum(["small", "medium"]).nullable(),
+    appWrite: false
+  }
+};
+var CONTROL_KEYS = Object.keys(CONTROLS);
+function parseOne(entry, schema) {
+  if (typeof entry !== "object" || entry === null) {
+    return { ok: false, reason: "not provided by the platform" };
+  }
+  const record = entry;
+  if (record.ok === false) {
+    return {
+      ok: false,
+      reason: typeof record.reason === "string" ? record.reason : "unavailable"
+    };
+  }
+  if (record.ok !== true) {
+    return { ok: false, reason: "malformed control" };
+  }
+  const parsed = schema.safeParse(record.value);
+  if (!parsed.success) {
+    return { ok: false, reason: `invalid value: ${parsed.error.issues[0]?.message ?? "unknown"}` };
+  }
+  return { ok: true, value: parsed.data };
+}
+function parseControls(raw) {
+  const source = typeof raw === "object" && raw !== null && !Array.isArray(raw) ? raw : {};
+  const result = {};
+  for (const key of CONTROL_KEYS) {
+    result[key] = parseOne(source[key], CONTROLS[key].schema);
+  }
+  return result;
+}
+function unavailableControls(reason) {
+  const result = {};
+  for (const key of CONTROL_KEYS) result[key] = { ok: false, reason };
+  return result;
+}
+
+// src/server/client.ts
+var import_server = require("@stardeck-customer-apps/kernel/server");
+
+// src/server/state.ts
+var CONTROLS_STATE_SYMBOL = /* @__PURE__ */ Symbol.for("stardeck.controls.state");
+function createControlsState() {
+  const state = {
+    cache: null,
+    inflight: null,
+    failure: null,
+    generation: 0,
+    usageProvider: null,
+    configKey: null,
+    warnedNotConfigured: false,
+    reset() {
+      state.cache = null;
+      state.inflight = null;
+      state.failure = null;
+      state.generation += 1;
+    }
+  };
+  return state;
+}
+function getGlobalControlsState() {
+  const holder = globalThis;
+  holder[CONTROLS_STATE_SYMBOL] ??= createControlsState();
+  return holder[CONTROLS_STATE_SYMBOL];
+}
+
+// src/server/client.ts
+var DEFAULT_TTL_MS = 6e4;
+var FAILURE_BACKOFF_MS = 5e3;
+var DEFAULT_STALE_TIMEOUT_MS = 1500;
+var DEFAULT_SYNC_TIMEOUT_MS = 3e3;
+var DEFAULT_WRITE_TIMEOUT_MS = 1e4;
+var USAGE_TIMEOUT_MS = 1e3;
+var USER_TOKEN_HEADER = "X-Stardeck-User-Token";
+var WRITE_ERROR_CODES = /* @__PURE__ */ new Set([
+  "NOT_WRITABLE",
+  "INVALID_VALUE",
+  "UNAUTHENTICATED",
+  "FORBIDDEN",
+  "WRITE_NOT_ALLOWED_HERE",
+  "PROVIDER_NOT_READY",
+  "UNAVAILABLE"
+]);
+function describeError(error) {
+  return error instanceof Error ? error.message : String(error);
+}
+function isRecord(value) {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function sanitizeUsage(usage) {
+  const clean = {};
+  if (Number.isInteger(usage.locations) && usage.locations >= 0) {
+    clean.locations = usage.locations;
+  }
+  return clean;
+}
+function parseWriteError(status, body) {
+  const error = isRecord(body) && isRecord(body.error) ? body.error : null;
+  if (error && typeof error.code === "string" && WRITE_ERROR_CODES.has(error.code)) {
+    return {
+      code: error.code,
+      message: typeof error.message === "string" ? error.message : `Request failed (${status})`,
+      ...typeof error.connectUrl === "string" ? { connectUrl: error.connectUrl } : {}
+    };
+  }
+  return {
+    code: "UNAVAILABLE",
+    message: `The platform answered ${status} without a usable error`
+  };
+}
+async function readJson(response) {
+  try {
+    return await response.json();
+  } catch {
+    return null;
+  }
+}
+async function withTimeout(promise, ms) {
+  let timer;
+  const timeout = new Promise((_, reject) => {
+    timer = setTimeout(() => reject(new Error(`timed out after ${ms}ms`)), ms);
+  });
+  try {
+    return await Promise.race([promise, timeout]);
+  } finally {
+    clearTimeout(timer);
+  }
+}
+function createControlsClientWithState(config, state) {
+  const doFetch = config.fetch ?? ((input, init) => globalThis.fetch(input, init));
+  const now = config.now ?? Date.now;
+  const ttlMs = config.ttlMs ?? DEFAULT_TTL_MS;
+  const staleTimeoutMs = config.staleTimeoutMs ?? DEFAULT_STALE_TIMEOUT_MS;
+  const syncTimeoutMs = config.requestTimeoutMs ?? DEFAULT_SYNC_TIMEOUT_MS;
+  const writeTimeoutMs = config.requestTimeoutMs ?? DEFAULT_WRITE_TIMEOUT_MS;
+  const usageTimeoutMs = Math.min(USAGE_TIMEOUT_MS, syncTimeoutMs);
+  const baseUrl = `${config.controlPlaneUrl.replace(/\/+$/, "")}/api/deployments/${encodeURIComponent(config.deploymentId)}/controls`;
+  function signedHeaders(extra) {
+    return {
+      "Content-Type": "application/json",
+      "X-Stardeck-Auth": (0, import_server.signDeploymentRequest)(config.deploymentSecret, {
+        organizationId: config.organizationId,
+        projectId: config.projectId,
+        deploymentId: config.deploymentId
+      }),
+      ...extra
+    };
+  }
+  async function collectUsage() {
+    const provider = config.usage ?? state.usageProvider;
+    if (!provider) return void 0;
+    try {
+      return sanitizeUsage(await withTimeout(Promise.resolve().then(provider), usageTimeoutMs));
+    } catch (error) {
+      console.error(
+        `[controls] usage provider failed, syncing without usage: ${describeError(error)}`
+      );
+      return void 0;
+    }
+  }
+  async function fetchControls() {
+    const usage = await collectUsage();
+    const body = usage ? { usage } : {};
+    const response = await doFetch(baseUrl, {
+      method: "POST",
+      headers: signedHeaders(),
+      body: JSON.stringify(body),
+      signal: AbortSignal.timeout(syncTimeoutMs)
+    });
+    if (!response.ok) {
+      throw new Error(`the platform answered ${response.status}`);
+    }
+    const json = await readJson(response);
+    if (!isRecord(json) || !isRecord(json.controls)) {
+      throw new Error("the platform answered without a controls map");
+    }
+    return parseControls(json.controls);
+  }
+  function recordFailure(generation, reason) {
+    if (generation !== state.generation) return;
+    const until = now() + FAILURE_BACKOFF_MS;
+    if (state.cache) {
+      state.cache.expiresAt = until;
+    } else {
+      state.failure = { until, reason };
+    }
+  }
+  async function runSync() {
+    const generation = state.generation;
+    try {
+      const controls = await fetchControls();
+      if (generation === state.generation) {
+        state.cache = { controls, expiresAt: now() + ttlMs };
+        state.failure = null;
+      }
+      return controls;
+    } catch (error) {
+      const reason = `controls sync failed: ${describeError(error)}`;
+      console.error(`[controls] refresh failed deployment=${config.deploymentId} ${reason}`);
+      recordFailure(generation, reason);
+      throw new Error(reason);
+    }
+  }
+  function startSync() {
+    if (state.inflight) return state.inflight;
+    const promise = runSync();
+    state.inflight = promise;
+    const clear = () => {
+      if (state.inflight === promise) state.inflight = null;
+    };
+    promise.then(clear, clear);
+    return promise;
+  }
+  async function load() {
+    const current = now();
+    const cache = state.cache;
+    if (cache && current < cache.expiresAt) return cache.controls;
+    if (!cache && state.failure && current < state.failure.until) {
+      return unavailableControls(state.failure.reason);
+    }
+    const sync = startSync();
+    if (!cache) {
+      try {
+        return await sync;
+      } catch (error) {
+        return unavailableControls(describeError(error));
+      }
+    }
+    try {
+      return await withTimeout(sync, staleTimeoutMs);
+    } catch (error) {
+      console.log(
+        `[controls] serving last value deployment=${config.deploymentId} (${describeError(error)})`
+      );
+      return state.cache?.controls ?? cache.controls;
+    }
+  }
+  async function write(key, value, userToken) {
+    const body = { value };
+    let response;
+    try {
+      response = await doFetch(`${baseUrl}/${encodeURIComponent(key)}`, {
+        method: "PUT",
+        headers: signedHeaders({ [USER_TOKEN_HEADER]: userToken }),
+        body: JSON.stringify(body),
+        signal: AbortSignal.timeout(writeTimeoutMs)
+      });
+    } catch (error) {
+      console.error(`[controls] write failed key=${key}: ${describeError(error)}`);
+      return { ok: false, error: { code: "UNAVAILABLE", message: describeError(error) } };
+    }
+    const json = await readJson(response);
+    if (!response.ok) {
+      const error = parseWriteError(response.status, json);
+      console.log(
+        `[controls] write refused key=${key} status=${response.status} code=${error.code}`
+      );
+      return { ok: false, error };
+    }
+    if (!isRecord(json) || !isRecord(json.controls)) {
+      console.error(`[controls] write answered without a controls map key=${key}`);
+      return {
+        ok: false,
+        error: { code: "UNAVAILABLE", message: "The platform answered without the new controls" }
+      };
+    }
+    const controls = parseControls(json.controls);
+    state.generation += 1;
+    state.cache = { controls, expiresAt: now() + ttlMs };
+    state.failure = null;
+    console.log(`[controls] write applied key=${key}`);
+    return { ok: true, controls };
+  }
+  return {
+    async get(key) {
+      return (await load())[key];
+    },
+    getAll: load,
+    async set(key, value, opts) {
+      return write(key, value, opts.userToken);
+    },
+    async refresh() {
+      try {
+        return await startSync();
+      } catch (error) {
+        return state.cache?.controls ?? unavailableControls(describeError(error));
+      }
+    }
+  };
+}
+function createControlsClient(config) {
+  return createControlsClientWithState(config, createControlsState());
+}
+
+// src/server/index.ts
+var NOT_CONFIGURED = "not configured";
+function readEnvConfig() {
+  const controlPlaneUrl = process.env.CONTROL_PLANE_URL;
+  const organizationId = process.env.ORGANIZATION_ID;
+  const projectId = process.env.PROJECT_ID;
+  const deploymentId = process.env.DEPLOYMENT_ID;
+  const deploymentSecret = process.env.DEPLOYMENT_SECRET;
+  if (!controlPlaneUrl || !organizationId || !projectId || !deploymentId || !deploymentSecret) {
+    return null;
+  }
+  return { controlPlaneUrl, organizationId, projectId, deploymentId, deploymentSecret };
+}
+function envClient() {
+  const state = getGlobalControlsState();
+  const config = readEnvConfig();
+  if (!config) {
+    if (!state.warnedNotConfigured) {
+      state.warnedNotConfigured = true;
+      console.warn(
+        "[controls] not configured: CONTROL_PLANE_URL, ORGANIZATION_ID, PROJECT_ID, DEPLOYMENT_ID and DEPLOYMENT_SECRET are required; every control reads as unavailable"
+      );
+    }
+    return null;
+  }
+  const configKey = `${config.controlPlaneUrl}|${config.deploymentId}|${config.deploymentSecret}`;
+  if (state.configKey !== configKey) {
+    state.reset();
+    state.configKey = configKey;
+  }
+  return createControlsClientWithState(config, state);
+}
+async function getControl(key) {
+  const client = envClient();
+  if (!client) return { ok: false, reason: NOT_CONFIGURED };
+  return client.get(key);
+}
+async function getControls() {
+  const client = envClient();
+  return client ? client.getAll() : unavailableControls(NOT_CONFIGURED);
+}
+async function refreshControls() {
+  const client = envClient();
+  return client ? client.refresh() : unavailableControls(NOT_CONFIGURED);
+}
+async function setControl(key, value, opts) {
+  const client = envClient();
+  if (!client) {
+    return {
+      ok: false,
+      error: { code: "UNAVAILABLE", message: "Controls are not configured for this app" }
+    };
+  }
+  return client.set(key, value, opts);
+}
+function setUsageProvider(fn) {
+  getGlobalControlsState().usageProvider = fn;
+}
+function resetControlsState() {
+  getGlobalControlsState().reset();
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  createControlsClient,
+  getControl,
+  getControls,
+  refreshControls,
+  resetControlsState,
+  setControl,
+  setUsageProvider
+});

package/dist/server/index.d.cts

@@ -0,0 +1,156 @@
+import { z } from 'zod';
+
+/**
+ * The controls list: every value the platform owns and an app reads.
+ *
+ * Isomorphic and data only. The platform imports this same list, so the
+ * platform and the app cannot disagree on a control's shape.
+ *
+ * Keys are never removed in future versions. An older app keeps asking for the
+ * keys it was built with, so a key can be added, never renamed or dropped.
+ * `appWrite: true` marks the few controls the app may change on a person's
+ * behalf (the platform still checks that person's permissions).
+ */
+declare const CONTROLS: {
+    readonly "flag.paymentsSetupStep": {
+        readonly schema: z.ZodBoolean;
+        readonly appWrite: false;
+    };
+    readonly "plan.locations": {
+        readonly schema: z.ZodObject<{
+            included: z.ZodNullable<z.ZodNumber>;
+            max: z.ZodNullable<z.ZodNumber>;
+            extraMonthly: z.ZodNullable<z.ZodObject<{
+                amount: z.ZodNumber;
+                currency: z.ZodEnum<{
+                    THB: "THB";
+                    USD: "USD";
+                }>;
+            }, z.core.$strip>>;
+        }, z.core.$strip>;
+        readonly appWrite: false;
+    };
+    readonly "plan.multiEntity": {
+        readonly schema: z.ZodBoolean;
+        readonly appWrite: false;
+    };
+    readonly "payments.provider": {
+        readonly schema: z.ZodNullable<z.ZodEnum<{
+            beam: "beam";
+            stripe: "stripe";
+        }>>;
+        readonly appWrite: true;
+    };
+    readonly "payments.methods": {
+        readonly schema: z.ZodObject<{
+            card: z.ZodBoolean;
+            promptPay: z.ZodBoolean;
+        }, z.core.$strip>;
+        readonly appWrite: true;
+    };
+    readonly "pos.pro": {
+        readonly schema: z.ZodObject<{
+            locations: z.ZodNullable<z.ZodNumber>;
+        }, z.core.$strip>;
+        readonly appWrite: false;
+    };
+    /**
+     * The Accounting Module edition the org pays for, each an add-on next to its plan. null means
+     * no Accounting plan: the app has no Accounting. `{ ok: false }` means unknown right now:
+     * refuse new accounting records and keep existing ones readable.
+     */
+    readonly "plan.accountingEdition": {
+        readonly schema: z.ZodNullable<z.ZodEnum<{
+            small: "small";
+            medium: "medium";
+        }>>;
+        readonly appWrite: false;
+    };
+};
+type ControlKey = keyof typeof CONTROLS;
+type ControlValue<K extends ControlKey> = z.infer<(typeof CONTROLS)[K]["schema"]>;
+/** One control as the app sees it. `ok: false` means "unknown right now". */
+type ControlResult<K extends ControlKey> = {
+    ok: true;
+    value: ControlValue<K>;
+} | {
+    ok: false;
+    reason: string;
+};
+type Controls = {
+    [K in ControlKey]: ControlResult<K>;
+};
+type WritableControlKey = {
+    [K in ControlKey]: (typeof CONTROLS)[K]["appWrite"] extends true ? K : never;
+}[ControlKey];
+/** What the app reports to the platform on every sync. Non-negative integers. */
+type ControlsUsage = {
+    locations?: number;
+};
+type ControlWriteErrorCode = "NOT_WRITABLE" | "INVALID_VALUE" | "UNAUTHENTICATED" | "FORBIDDEN" | "WRITE_NOT_ALLOWED_HERE" | "PROVIDER_NOT_READY" | "UNAVAILABLE";
+type ControlWriteError = {
+    code: ControlWriteErrorCode;
+    message: string;
+    /** Where the person finishes connecting a provider, when that is the blocker. */
+    connectUrl?: string;
+};
+
+interface ControlsClientConfig {
+    controlPlaneUrl: string;
+    organizationId: string;
+    projectId: string;
+    deploymentId: string;
+    deploymentSecret: string;
+    ttlMs?: number;
+    /** How long a stale cache waits for a refresh before serving the last value. */
+    staleTimeoutMs?: number;
+    /** Network timeout of one request to the platform (default 3s for a sync, 10s for a write). */
+    requestTimeoutMs?: number;
+    fetch?: typeof fetch;
+    now?: () => number;
+    /** Reports usage on each sync. Errors are logged and usage is omitted. */
+    usage?: () => Promise<ControlsUsage>;
+}
+type SetControlResult = {
+    ok: true;
+    controls: Controls;
+} | {
+    ok: false;
+    error: ControlWriteError;
+};
+interface ControlsClient {
+    get<K extends ControlKey>(key: K): Promise<ControlResult<K>>;
+    getAll(): Promise<Controls>;
+    set<K extends WritableControlKey>(key: K, value: ControlValue<K>, opts: {
+        userToken: string;
+    }): Promise<SetControlResult>;
+    /** Forces a sync now, ignoring the TTL. Resolves with the controls it served. */
+    refresh(): Promise<Controls>;
+}
+declare function createControlsClient(config: ControlsClientConfig): ControlsClient;
+
+/** One control. `{ ok: false }` when the platform can't be reached or doesn't provide it. */
+declare function getControl<K extends ControlKey>(key: K): Promise<ControlResult<K>>;
+declare function getControls(): Promise<Controls>;
+/**
+ * Asks the platform now, ignoring the cache (for example after it refused a payment because the
+ * provider changed). Concurrent callers share one request; on failure the last values stay.
+ */
+declare function refreshControls(): Promise<Controls>;
+/**
+ * Changes a control the app may write, on behalf of the signed-in person. The
+ * person's session token travels in `X-Stardeck-User-Token`; the platform
+ * checks that person's permissions and refuses the write otherwise.
+ */
+declare function setControl<K extends WritableControlKey>(key: K, value: ControlValue<K>, opts: {
+    userToken: string;
+}): Promise<SetControlResult>;
+/**
+ * Registers what the app reports on every sync (for example its active
+ * location count). Called each sync; an error is logged and usage is omitted.
+ */
+declare function setUsageProvider(fn: () => Promise<ControlsUsage>): void;
+/** Drops the process cache (used by the testing simulator). */
+declare function resetControlsState(): void;
+
+export { type ControlsClient, type ControlsClientConfig, type SetControlResult, createControlsClient, getControl, getControls, refreshControls, resetControlsState, setControl, setUsageProvider };