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

package/SKILL.md

@@ -0,0 +1,129 @@
+# Controls: what Stardeck decides for your app
+
+**Package**: `@stardeck-customer-apps/controls`
+
+Controls are values Stardeck owns and your app reads while it runs: feature
+flags, what the plan allows, and which payment provider and methods the app
+uses. Your app asks Stardeck about once a minute and keeps the answer in memory.
+A change on Stardeck reaches the app within about a minute, with no deploy.
+
+Never invent controls or flags of your own. The list is fixed by Stardeck and
+shipped in this package. If a behavior needs a switch that is not on the list,
+store it as an app setting instead.
+
+## Reading a control
+
+```ts
+import { getControl, getControls } from "@stardeck-customer-apps/controls/server";
+
+const multiEntity = await getControl("plan.multiEntity");
+if (multiEntity.ok && multiEntity.value) {
+  // allow a second company
+}
+```
+
+`getControl(key)` never throws. It returns `{ ok: true, value }` or
+`{ ok: false, reason }`. `ok: false` means "unknown right now" (Stardeck could
+not be reached on a cold start, or the value was not provided). It does **not**
+mean the feature is off, and it does not mean the limit is unlimited. Handle it:
+
+- Refuse the new thing (a new location, a new company, a new checkout) with a
+  retry message.
+- Keep everything that already exists working (sales, bookings, reads).
+- Do not cache `ok: false` yourself.
+
+After the first success the app keeps serving the last good value if Stardeck is
+briefly unreachable, so `ok: false` is rare in practice.
+
+`getControls()` returns every control at once. The cache lives for the life of
+the server process and is shared by every request. `refreshControls()` asks the
+platform now, ignoring the cache; use it when the platform has just told you a
+value moved (a payment refused with `PROVIDER_CHANGED`). If that request fails,
+the last values stay.
+
+## The controls
+
+| Key                      | Value                                                                                           | App may write |
+| ------------------------ | ----------------------------------------------------------------------------------------------- | ------------- |
+| `flag.paymentsSetupStep` | `boolean`                                                                                       | no            |
+| `plan.locations`         | `{ included: number \| null, max: number \| null, extraMonthly: { amount, currency } \| null }` | no            |
+| `plan.multiEntity`       | `boolean`                                                                                       | no            |
+| `payments.provider`      | `"beam" \| "stripe" \| null`                                                                    | yes           |
+| `payments.methods`       | `{ card: boolean, promptPay: boolean }`                                                         | yes           |
+
+- `plan.locations.included` is what the plan covers. `max` is a hard cap (the
+  entry plan has 1); `null` means no cap, and each location past `included` is
+  billed at `extraMonthly`. `included: null` means the number was agreed per deal.
+- Keys are never removed in later versions, so code written against today's list
+  keeps working.
+
+Types and the list itself are in the root export:
+
+```ts
+import { CONTROLS, parseControls, type ControlKey } from "@stardeck-customer-apps/controls";
+```
+
+## Changing provider or methods
+
+Only `payments.provider` and `payments.methods` can be changed from the app, and
+only on behalf of a signed-in person. Pass that person's session token. Stardeck
+checks that this person may change the app's settings; the app's own roles are
+never enough.
+
+```ts
+import { cookies } from "next/headers";
+import { setControl } from "@stardeck-customer-apps/controls/server";
+
+// The token is the project-auth session cookie "__stardeck:sess", the same one
+// AuthManagementClient sends as X-Stardeck-User-Token.
+const userToken = (await cookies()).get("__stardeck:sess")?.value;
+if (!userToken) return unauthorized();
+
+const result = await setControl("payments.provider", "stripe", { userToken });
+if (!result.ok) {
+  // result.error.code: NOT_WRITABLE | INVALID_VALUE | UNAUTHENTICATED | FORBIDDEN |
+  //   WRITE_NOT_ALLOWED_HERE | PROVIDER_NOT_READY | UNAVAILABLE
+  // PROVIDER_NOT_READY carries result.error.connectUrl: send the person there to
+  // finish connecting, and they come back with the provider switched on.
+  // WRITE_NOT_ALLOWED_HERE: previews and stagings change this on Stardeck instead.
+  return refuse(result.error);
+}
+// result.controls is the fresh set; the app's cache already has it.
+```
+
+Show `error.message` to the person. Do not retry `FORBIDDEN` or
+`WRITE_NOT_ALLOWED_HERE`. A successful write refreshes this server immediately;
+other server instances catch up within a minute. Payment creation is checked
+live by Stardeck, so a stale instance cannot charge on the old provider.
+
+## Reporting usage
+
+Stardeck bills extra locations from what the app reports. Register a provider
+once at startup; it runs on every sync (about once a minute per server):
+
+```ts
+import { setUsageProvider } from "@stardeck-customer-apps/controls/server";
+
+setUsageProvider(async () => ({ locations: await countActiveLocations() }));
+```
+
+Report non-negative integers only, counted from the app's own rows. Keep the
+count to one quick query: if the provider throws or takes longer than a second,
+the error is logged and that sync goes without usage.
+
+## Configuration
+
+The client reads `CONTROL_PLANE_URL`,
+`ORGANIZATION_ID`, `PROJECT_ID`, `DEPLOYMENT_ID` and `DEPLOYMENT_SECRET`, the same
+deployment env the other Stardeck SDKs use. If any is missing, every control
+reads `{ ok: false, reason: "not configured" }` and one warning is logged. For
+custom wiring use `createControlsClient({ controlPlaneUrl, organizationId, projectId, deploymentId, deploymentSecret })`.
+
+## Testing
+
+`@stardeck-customer-apps/testing` simulates the sync and write routes:
+`createTestApp({ controls: { "plan.multiEntity": false } })`, then
+`app.controls.set(key, value)`, `app.controls.setUnavailable(key)`,
+`app.controls.lastUsage()`, `app.controls.writes()` and
+`app.controls.refuseNextWrite({ code, message, connectUrl })`. A `set` is visible
+to the next `getControl` call immediately. Always cover the `ok: false` path.

package/dist/index.cjs

@@ -0,0 +1,105 @@
+"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/index.ts
+var index_exports = {};
+__export(index_exports, {
+  CONTROLS: () => CONTROLS,
+  CONTROL_KEYS: () => CONTROL_KEYS,
+  isControlKey: () => isControlKey,
+  isWritableControl: () => isWritableControl,
+  parseControls: () => parseControls,
+  unavailableControls: () => unavailableControls
+});
+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
+  }
+};
+var CONTROL_KEYS = Object.keys(CONTROLS);
+function isControlKey(key) {
+  return Object.prototype.hasOwnProperty.call(CONTROLS, key);
+}
+function isWritableControl(key) {
+  return isControlKey(key) && CONTROLS[key].appWrite === true;
+}
+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;
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  CONTROLS,
+  CONTROL_KEYS,
+  isControlKey,
+  isWritableControl,
+  parseControls,
+  unavailableControls
+});

package/dist/index.d.cts

@@ -0,0 +1,103 @@
+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;
+    };
+};
+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;
+};
+/** POST /api/deployments/{deploymentId}/controls body. */
+type ControlsSyncRequest = {
+    usage?: ControlsUsage;
+};
+/** POST response. Each value is `{ ok: true, value }` or `{ ok: false, reason }`. */
+type ControlsSyncResponse = {
+    controls: Record<string, unknown>;
+};
+/** PUT /api/deployments/{deploymentId}/controls/{key} body. The person's session goes in `X-Stardeck-User-Token`. */
+type ControlWriteRequest = {
+    value: unknown;
+};
+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;
+};
+declare const CONTROL_KEYS: ControlKey[];
+declare function isControlKey(key: string): key is ControlKey;
+declare function isWritableControl(key: string): key is WritableControlKey;
+/**
+ * Validates the platform's `controls` map. Each key is validated on its own: a
+ * missing or invalid key becomes `{ ok: false, reason }` and never poisons the
+ * others. Keys this version does not know are ignored.
+ */
+declare function parseControls(raw: unknown): Controls;
+/** Every control unavailable for one reason (cold start with the platform down, or not configured). */
+declare function unavailableControls(reason: string): Controls;
+
+export { CONTROLS, CONTROL_KEYS, type ControlKey, type ControlResult, type ControlValue, type ControlWriteError, type ControlWriteErrorCode, type ControlWriteRequest, type Controls, type ControlsSyncRequest, type ControlsSyncResponse, type ControlsUsage, type WritableControlKey, isControlKey, isWritableControl, parseControls, unavailableControls };

package/dist/index.d.ts

@@ -0,0 +1,103 @@
+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;
+    };
+};
+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;
+};
+/** POST /api/deployments/{deploymentId}/controls body. */
+type ControlsSyncRequest = {
+    usage?: ControlsUsage;
+};
+/** POST response. Each value is `{ ok: true, value }` or `{ ok: false, reason }`. */
+type ControlsSyncResponse = {
+    controls: Record<string, unknown>;
+};
+/** PUT /api/deployments/{deploymentId}/controls/{key} body. The person's session goes in `X-Stardeck-User-Token`. */
+type ControlWriteRequest = {
+    value: unknown;
+};
+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;
+};
+declare const CONTROL_KEYS: ControlKey[];
+declare function isControlKey(key: string): key is ControlKey;
+declare function isWritableControl(key: string): key is WritableControlKey;
+/**
+ * Validates the platform's `controls` map. Each key is validated on its own: a
+ * missing or invalid key becomes `{ ok: false, reason }` and never poisons the
+ * others. Keys this version does not know are ignored.
+ */
+declare function parseControls(raw: unknown): Controls;
+/** Every control unavailable for one reason (cold start with the platform down, or not configured). */
+declare function unavailableControls(reason: string): Controls;
+
+export { CONTROLS, CONTROL_KEYS, type ControlKey, type ControlResult, type ControlValue, type ControlWriteError, type ControlWriteErrorCode, type ControlWriteRequest, type Controls, type ControlsSyncRequest, type ControlsSyncResponse, type ControlsUsage, type WritableControlKey, isControlKey, isWritableControl, parseControls, unavailableControls };

package/dist/index.js

@@ -0,0 +1,73 @@
+// 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 isControlKey(key) {
+  return Object.prototype.hasOwnProperty.call(CONTROLS, key);
+}
+function isWritableControl(key) {
+  return isControlKey(key) && CONTROLS[key].appWrite === true;
+}
+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;
+}
+export {
+  CONTROLS,
+  CONTROL_KEYS,
+  isControlKey,
+  isWritableControl,
+  parseControls,
+  unavailableControls
+};