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

package/dist/server/index.js

@@ -0,0 +1,387 @@
+// src/controls.ts
+import { z } from "zod";
+var CONTROLS = {
+  "flag.paymentsSetupStep": { schema: z.boolean(), appWrite: false },
+  "plan.locations": {
+    schema: z.object({
+      /** Locations the plan includes. null = agreed per deal. */
+      included: z.number().int().positive().nullable(),
+      /** Hard cap. Platform plan: 1; others: null (no cap, extras are billed). */
+      max: z.number().int().positive().nullable(),
+      /** Monthly price of each location past `included`. null = not offered. */
+      extraMonthly: z.object({
+        amount: z.number().nonnegative(),
+        currency: z.enum(["THB", "USD"])
+      }).nullable()
+    }),
+    appWrite: false
+  },
+  "plan.multiEntity": { schema: z.boolean(), appWrite: false },
+  "payments.provider": { schema: z.enum(["beam", "stripe"]).nullable(), appWrite: true },
+  "payments.methods": {
+    schema: z.object({ card: z.boolean(), promptPay: z.boolean() }),
+    appWrite: true
+  }
+};
+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
+import { signDeploymentRequest } from "@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": 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();
+}
+export {
+  createControlsClient,
+  getControl,
+  getControls,
+  refreshControls,
+  resetControlsState,
+  setControl,
+  setUsageProvider
+};

package/package.json

@@ -1,6 +1,66 @@
 {
   "name": "@stardeck-customer-apps/controls",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "type": "module",
+  "version": "0.1.0",
+  "description": "Platform-owned app controls (feature flags, plan limits, payment provider and methods) for Stardeck customer apps: a typed list plus a cached, signed sync client",
+  "main": "dist/index.cjs",
+  "module": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "publishConfig": {
+    "registry": "https://registry.npmjs.org/",
+    "access": "public"
+  },
+  "files": [
+    "dist",
+    "SKILL.md"
+  ],
+  "exports": {
+    ".": {
+      "import": {
+        "types": "./dist/index.d.ts",
+        "default": "./dist/index.js"
+      },
+      "require": {
+        "types": "./dist/index.d.cts",
+        "default": "./dist/index.cjs"
+      }
+    },
+    "./server": {
+      "import": {
+        "types": "./dist/server/index.d.ts",
+        "default": "./dist/server/index.js"
+      },
+      "require": {
+        "types": "./dist/server/index.d.cts",
+        "default": "./dist/server/index.cjs"
+      }
+    }
+  },
+  "scripts": {
+    "build": "tsup",
+    "dev": "tsup --watch",
+    "format": "prettier --write . && oxlint . --fix",
+    "typecheck": "node ../../scripts/typecheck.mjs --noEmit",
+    "lint": "oxlint src/",
+    "test": "vitest run"
+  },
+  "keywords": [
+    "stardeck",
+    "controls",
+    "feature-flags",
+    "plan-limits"
+  ],
+  "author": "Stardeck",
+  "license": "MIT",
+  "dependencies": {
+    "@stardeck-customer-apps/kernel": "^0.1.0",
+    "zod": "^4.1.12"
+  },
+  "devDependencies": {
+    "@stardeck-customer-apps/tsconfig": "*",
+    "@types/node": "^24.10.1",
+    "tsup": "^8.0.0",
+    "typescript": "^5.0.0",
+    "vitest": "^3.2.4"
+  }
+}

package/README.md

@@ -1,3 +0,0 @@
-# Temporary Holding Version
-
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.