@stardeck-customer-apps/controls 0.3.0 → 0.4.0

package/SKILL.md

@@ -4,8 +4,9 @@
 
 Controls are values Stardeck owns and your app reads while it runs: feature
 flags, what the plan allows, how many locations have POS Pro hardware, which
-Accounting edition the business pays for, and which payment provider and methods
-the app uses. Your app asks Stardeck about once a minute and keeps the answer in memory.
+Accounting edition the business pays for, which payment provider and methods
+the app uses, and who the business is (its name, address, tax ID, currency and
+time zone). 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
@@ -53,6 +54,7 @@ the last values stay.
 | `plan.accountingEdition` | `"small" \| "medium" \| null`                                                                   | no            |
 | `payments.provider`      | `"beam" \| "stripe" \| null`                                                                    | yes           |
 | `payments.methods`       | `{ card: boolean, promptPay: boolean }`                                                         | yes           |
+| `business.profile`       | `BusinessProfile \| null` (see "Business details")                                              | 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
@@ -63,6 +65,9 @@ the last values stay.
 - `plan.accountingEdition` is the Accounting edition the business pays for, an
   add-on next to its plan. `null` means it has no Accounting plan. See
   "Accounting edition" below.
+- `business.profile` is the business the app is for, as Stardeck keeps it for
+  the organization. `null` means Stardeck has no record yet. See "Business
+  details" below.
 - Keys are never removed in later versions, so code written against today's list
   keeps working.
 
@@ -116,6 +121,53 @@ if (edition.value === null) {
 // edition.value is "small" or "medium"
 ```
 
+## Business details
+
+Stardeck keeps one business record per organization: what the owner told
+Stardeck when they signed up, edited in Stardeck's Business settings. Every app
+in the organization reads the same record (needs controls 0.4.0 or later):
+
+```ts
+type BusinessProfile = {
+  kind: string; // a business preset id: "restaurant", "spa", "general"…
+  name: { en: string; th: string | null };
+  headOfficeAddress: string | null;
+  taxId: string | null;
+  country: string; // ISO 3166-1 alpha-2, "TH"
+  currency: string; // ISO 4217, "THB"
+  timezone: string; // IANA, "Asia/Bangkok"
+};
+```
+
+Stardeck owns it; the app keeps a copy. Mirror it into the app's own records
+(the default company, the currency and time zone settings, the business preset)
+whenever the value differs from what the app holds:
+
+- `{ ok: true, value }`: copy `value` into the app. A `kind` this app does not
+  have stays on the general preset; never fail on it.
+- `{ ok: true, value: null }`: Stardeck has no record yet. If the app already
+  has its own company details, send them up once with `setControl`; otherwise
+  ask the owner as before.
+- `ok: false`: unknown right now, which is not the same as `null`. Change
+  nothing and keep the company the app has. Never blank a name or address
+  because of `ok: false`.
+
+When the owner edits the business inside the app, write it to Stardeck first
+with `setControl("business.profile", profile, { userToken })`, then save the
+app's own copy from the answer. Saving only the app's copy would be undone by
+the next mirror. Only an admin of the organization on Stardeck may write it, so
+a `FORBIDDEN` answer means "ask an organization admin"; show `error.message`.
+`null` is refused (`INVALID_VALUE`): the app can change the details but not
+remove them. Validate input with the same rules Stardeck uses:
+
+```ts
+import { businessProfileSchema } from "@stardeck-customer-apps/controls";
+
+const parsed = businessProfileSchema.safeParse(input);
+if (!parsed.success) return badRequest(parsed.error.issues[0]?.message);
+const result = await setControl("business.profile", parsed.data, { userToken });
+```
+
 Types and the list itself are in the root export:
 
 ```ts
@@ -124,10 +176,11 @@ import { CONTROLS, parseControls, type ControlKey } from "@stardeck-customer-app
 
 ## 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.
+Only `payments.provider`, `payments.methods` and `business.profile` 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 (for `business.profile`, that they are an admin of the organization);
+the app's own roles are never enough.
 
 ```ts
 import { cookies } from "next/headers";

package/dist/index.cjs

@@ -22,6 +22,7 @@ var index_exports = {};
 __export(index_exports, {
   CONTROLS: () => CONTROLS,
   CONTROL_KEYS: () => CONTROL_KEYS,
+  businessProfileSchema: () => businessProfileSchema,
   isControlKey: () => isControlKey,
   isWritableControl: () => isWritableControl,
   parseControls: () => parseControls,
@@ -31,6 +32,33 @@ module.exports = __toCommonJS(index_exports);
 
 // src/controls.ts
 var import_zod = require("zod");
+function isIanaTimeZone(value) {
+  try {
+    new Intl.DateTimeFormat("en", { timeZone: value });
+    return true;
+  } catch {
+    return false;
+  }
+}
+var businessProfileSchema = import_zod.z.object({
+  /** The kind of business: a business preset id the app defines (`restaurant`, `spa`, `general`…). */
+  kind: import_zod.z.string().regex(/^[a-z][a-z0-9-]{0,39}$/, "a business kind is a lowercase preset id"),
+  /** The company's name. Thai is null when the business has no Thai name. */
+  name: import_zod.z.object({
+    en: import_zod.z.string().trim().min(1, "the business needs a name").max(200),
+    th: import_zod.z.string().trim().min(1).max(200).nullable()
+  }),
+  /** Head-office address as one block of text; null until someone enters it. */
+  headOfficeAddress: import_zod.z.string().trim().min(1).max(1e3).nullable(),
+  /** Tax ID; null for a business with none (under the VAT threshold, say). */
+  taxId: import_zod.z.string().trim().min(1).max(40).nullable(),
+  /** ISO 3166-1 alpha-2. */
+  country: import_zod.z.string().regex(/^[A-Z]{2}$/, "country is an ISO 3166-1 alpha-2 code"),
+  /** ISO 4217. */
+  currency: import_zod.z.string().regex(/^[A-Z]{3}$/, "currency is an ISO 4217 code"),
+  /** IANA time zone. */
+  timezone: import_zod.z.string().refine(isIanaTimeZone, "timezone is not an IANA time zone")
+});
 var CONTROLS = {
   "flag.paymentsSetupStep": { schema: import_zod.z.boolean(), appWrite: false },
   "plan.locations": {
@@ -68,7 +96,13 @@ var CONTROLS = {
   "plan.accountingEdition": {
     schema: import_zod.z.enum(["small", "medium"]).nullable(),
     appWrite: false
-  }
+  },
+  /**
+   * The business this app is for, owned by Stardeck. null means Stardeck has no record yet: an
+   * app that already has its own company details sends them up once. `{ ok: false }` means
+   * unknown right now: keep the company the app has.
+   */
+  "business.profile": { schema: businessProfileSchema.nullable(), appWrite: true }
 };
 var CONTROL_KEYS = Object.keys(CONTROLS);
 function isControlKey(key) {
@@ -114,6 +148,7 @@ function unavailableControls(reason) {
 0 && (module.exports = {
   CONTROLS,
   CONTROL_KEYS,
+  businessProfileSchema,
   isControlKey,
   isWritableControl,
   parseControls,

package/dist/index.d.cts

@@ -1,5 +1,23 @@
 import { z } from 'zod';
 
+/**
+ * Who the business is, as Stardeck keeps it for the org: what onboarding asks and Stardeck's
+ * Business settings edit. The app mirrors it into its default company and workspace settings, and
+ * sends an owner's edit back through this same control, so Stardeck stays the one source.
+ */
+declare const businessProfileSchema: z.ZodObject<{
+    kind: z.ZodString;
+    name: z.ZodObject<{
+        en: z.ZodString;
+        th: z.ZodNullable<z.ZodString>;
+    }, z.core.$strip>;
+    headOfficeAddress: z.ZodNullable<z.ZodString>;
+    taxId: z.ZodNullable<z.ZodString>;
+    country: z.ZodString;
+    currency: z.ZodString;
+    timezone: z.ZodString;
+}, z.core.$strip>;
+type BusinessProfile = z.infer<typeof businessProfileSchema>;
 /**
  * The controls list: every value the platform owns and an app reads.
  *
@@ -66,6 +84,26 @@ declare const CONTROLS: {
         }>>;
         readonly appWrite: false;
     };
+    /**
+     * The business this app is for, owned by Stardeck. null means Stardeck has no record yet: an
+     * app that already has its own company details sends them up once. `{ ok: false }` means
+     * unknown right now: keep the company the app has.
+     */
+    readonly "business.profile": {
+        readonly schema: z.ZodNullable<z.ZodObject<{
+            kind: z.ZodString;
+            name: z.ZodObject<{
+                en: z.ZodString;
+                th: z.ZodNullable<z.ZodString>;
+            }, z.core.$strip>;
+            headOfficeAddress: z.ZodNullable<z.ZodString>;
+            taxId: z.ZodNullable<z.ZodString>;
+            country: z.ZodString;
+            currency: z.ZodString;
+            timezone: z.ZodString;
+        }, z.core.$strip>>;
+        readonly appWrite: true;
+    };
 };
 type ControlKey = keyof typeof CONTROLS;
 type ControlValue<K extends ControlKey> = z.infer<(typeof CONTROLS)[K]["schema"]>;
@@ -118,4 +156,4 @@ 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 };
+export { type BusinessProfile, 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, businessProfileSchema, isControlKey, isWritableControl, parseControls, unavailableControls };

package/dist/index.d.ts

@@ -1,5 +1,23 @@
 import { z } from 'zod';
 
+/**
+ * Who the business is, as Stardeck keeps it for the org: what onboarding asks and Stardeck's
+ * Business settings edit. The app mirrors it into its default company and workspace settings, and
+ * sends an owner's edit back through this same control, so Stardeck stays the one source.
+ */
+declare const businessProfileSchema: z.ZodObject<{
+    kind: z.ZodString;
+    name: z.ZodObject<{
+        en: z.ZodString;
+        th: z.ZodNullable<z.ZodString>;
+    }, z.core.$strip>;
+    headOfficeAddress: z.ZodNullable<z.ZodString>;
+    taxId: z.ZodNullable<z.ZodString>;
+    country: z.ZodString;
+    currency: z.ZodString;
+    timezone: z.ZodString;
+}, z.core.$strip>;
+type BusinessProfile = z.infer<typeof businessProfileSchema>;
 /**
  * The controls list: every value the platform owns and an app reads.
  *
@@ -66,6 +84,26 @@ declare const CONTROLS: {
         }>>;
         readonly appWrite: false;
     };
+    /**
+     * The business this app is for, owned by Stardeck. null means Stardeck has no record yet: an
+     * app that already has its own company details sends them up once. `{ ok: false }` means
+     * unknown right now: keep the company the app has.
+     */
+    readonly "business.profile": {
+        readonly schema: z.ZodNullable<z.ZodObject<{
+            kind: z.ZodString;
+            name: z.ZodObject<{
+                en: z.ZodString;
+                th: z.ZodNullable<z.ZodString>;
+            }, z.core.$strip>;
+            headOfficeAddress: z.ZodNullable<z.ZodString>;
+            taxId: z.ZodNullable<z.ZodString>;
+            country: z.ZodString;
+            currency: z.ZodString;
+            timezone: z.ZodString;
+        }, z.core.$strip>>;
+        readonly appWrite: true;
+    };
 };
 type ControlKey = keyof typeof CONTROLS;
 type ControlValue<K extends ControlKey> = z.infer<(typeof CONTROLS)[K]["schema"]>;
@@ -118,4 +156,4 @@ 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 };
+export { type BusinessProfile, 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, businessProfileSchema, isControlKey, isWritableControl, parseControls, unavailableControls };

package/dist/index.js

@@ -1,5 +1,32 @@
 // src/controls.ts
 import { z } from "zod";
+function isIanaTimeZone(value) {
+  try {
+    new Intl.DateTimeFormat("en", { timeZone: value });
+    return true;
+  } catch {
+    return false;
+  }
+}
+var businessProfileSchema = z.object({
+  /** The kind of business: a business preset id the app defines (`restaurant`, `spa`, `general`…). */
+  kind: z.string().regex(/^[a-z][a-z0-9-]{0,39}$/, "a business kind is a lowercase preset id"),
+  /** The company's name. Thai is null when the business has no Thai name. */
+  name: z.object({
+    en: z.string().trim().min(1, "the business needs a name").max(200),
+    th: z.string().trim().min(1).max(200).nullable()
+  }),
+  /** Head-office address as one block of text; null until someone enters it. */
+  headOfficeAddress: z.string().trim().min(1).max(1e3).nullable(),
+  /** Tax ID; null for a business with none (under the VAT threshold, say). */
+  taxId: z.string().trim().min(1).max(40).nullable(),
+  /** ISO 3166-1 alpha-2. */
+  country: z.string().regex(/^[A-Z]{2}$/, "country is an ISO 3166-1 alpha-2 code"),
+  /** ISO 4217. */
+  currency: z.string().regex(/^[A-Z]{3}$/, "currency is an ISO 4217 code"),
+  /** IANA time zone. */
+  timezone: z.string().refine(isIanaTimeZone, "timezone is not an IANA time zone")
+});
 var CONTROLS = {
   "flag.paymentsSetupStep": { schema: z.boolean(), appWrite: false },
   "plan.locations": {
@@ -37,7 +64,13 @@ var CONTROLS = {
   "plan.accountingEdition": {
     schema: z.enum(["small", "medium"]).nullable(),
     appWrite: false
-  }
+  },
+  /**
+   * The business this app is for, owned by Stardeck. null means Stardeck has no record yet: an
+   * app that already has its own company details sends them up once. `{ ok: false }` means
+   * unknown right now: keep the company the app has.
+   */
+  "business.profile": { schema: businessProfileSchema.nullable(), appWrite: true }
 };
 var CONTROL_KEYS = Object.keys(CONTROLS);
 function isControlKey(key) {
@@ -82,6 +115,7 @@ function unavailableControls(reason) {
 export {
   CONTROLS,
   CONTROL_KEYS,
+  businessProfileSchema,
   isControlKey,
   isWritableControl,
   parseControls,

package/dist/server/index.cjs

@@ -32,6 +32,33 @@ module.exports = __toCommonJS(index_exports);
 
 // src/controls.ts
 var import_zod = require("zod");
+function isIanaTimeZone(value) {
+  try {
+    new Intl.DateTimeFormat("en", { timeZone: value });
+    return true;
+  } catch {
+    return false;
+  }
+}
+var businessProfileSchema = import_zod.z.object({
+  /** The kind of business: a business preset id the app defines (`restaurant`, `spa`, `general`…). */
+  kind: import_zod.z.string().regex(/^[a-z][a-z0-9-]{0,39}$/, "a business kind is a lowercase preset id"),
+  /** The company's name. Thai is null when the business has no Thai name. */
+  name: import_zod.z.object({
+    en: import_zod.z.string().trim().min(1, "the business needs a name").max(200),
+    th: import_zod.z.string().trim().min(1).max(200).nullable()
+  }),
+  /** Head-office address as one block of text; null until someone enters it. */
+  headOfficeAddress: import_zod.z.string().trim().min(1).max(1e3).nullable(),
+  /** Tax ID; null for a business with none (under the VAT threshold, say). */
+  taxId: import_zod.z.string().trim().min(1).max(40).nullable(),
+  /** ISO 3166-1 alpha-2. */
+  country: import_zod.z.string().regex(/^[A-Z]{2}$/, "country is an ISO 3166-1 alpha-2 code"),
+  /** ISO 4217. */
+  currency: import_zod.z.string().regex(/^[A-Z]{3}$/, "currency is an ISO 4217 code"),
+  /** IANA time zone. */
+  timezone: import_zod.z.string().refine(isIanaTimeZone, "timezone is not an IANA time zone")
+});
 var CONTROLS = {
   "flag.paymentsSetupStep": { schema: import_zod.z.boolean(), appWrite: false },
   "plan.locations": {
@@ -69,7 +96,13 @@ var CONTROLS = {
   "plan.accountingEdition": {
     schema: import_zod.z.enum(["small", "medium"]).nullable(),
     appWrite: false
-  }
+  },
+  /**
+   * The business this app is for, owned by Stardeck. null means Stardeck has no record yet: an
+   * app that already has its own company details sends them up once. `{ ok: false }` means
+   * unknown right now: keep the company the app has.
+   */
+  "business.profile": { schema: businessProfileSchema.nullable(), appWrite: true }
 };
 var CONTROL_KEYS = Object.keys(CONTROLS);
 function parseOne(entry, schema) {

package/dist/server/index.d.cts

@@ -66,6 +66,26 @@ declare const CONTROLS: {
         }>>;
         readonly appWrite: false;
     };
+    /**
+     * The business this app is for, owned by Stardeck. null means Stardeck has no record yet: an
+     * app that already has its own company details sends them up once. `{ ok: false }` means
+     * unknown right now: keep the company the app has.
+     */
+    readonly "business.profile": {
+        readonly schema: z.ZodNullable<z.ZodObject<{
+            kind: z.ZodString;
+            name: z.ZodObject<{
+                en: z.ZodString;
+                th: z.ZodNullable<z.ZodString>;
+            }, z.core.$strip>;
+            headOfficeAddress: z.ZodNullable<z.ZodString>;
+            taxId: z.ZodNullable<z.ZodString>;
+            country: z.ZodString;
+            currency: z.ZodString;
+            timezone: z.ZodString;
+        }, z.core.$strip>>;
+        readonly appWrite: true;
+    };
 };
 type ControlKey = keyof typeof CONTROLS;
 type ControlValue<K extends ControlKey> = z.infer<(typeof CONTROLS)[K]["schema"]>;

package/dist/server/index.d.ts

@@ -66,6 +66,26 @@ declare const CONTROLS: {
         }>>;
         readonly appWrite: false;
     };
+    /**
+     * The business this app is for, owned by Stardeck. null means Stardeck has no record yet: an
+     * app that already has its own company details sends them up once. `{ ok: false }` means
+     * unknown right now: keep the company the app has.
+     */
+    readonly "business.profile": {
+        readonly schema: z.ZodNullable<z.ZodObject<{
+            kind: z.ZodString;
+            name: z.ZodObject<{
+                en: z.ZodString;
+                th: z.ZodNullable<z.ZodString>;
+            }, z.core.$strip>;
+            headOfficeAddress: z.ZodNullable<z.ZodString>;
+            taxId: z.ZodNullable<z.ZodString>;
+            country: z.ZodString;
+            currency: z.ZodString;
+            timezone: z.ZodString;
+        }, z.core.$strip>>;
+        readonly appWrite: true;
+    };
 };
 type ControlKey = keyof typeof CONTROLS;
 type ControlValue<K extends ControlKey> = z.infer<(typeof CONTROLS)[K]["schema"]>;

package/dist/server/index.js

@@ -1,5 +1,32 @@
 // src/controls.ts
 import { z } from "zod";
+function isIanaTimeZone(value) {
+  try {
+    new Intl.DateTimeFormat("en", { timeZone: value });
+    return true;
+  } catch {
+    return false;
+  }
+}
+var businessProfileSchema = z.object({
+  /** The kind of business: a business preset id the app defines (`restaurant`, `spa`, `general`…). */
+  kind: z.string().regex(/^[a-z][a-z0-9-]{0,39}$/, "a business kind is a lowercase preset id"),
+  /** The company's name. Thai is null when the business has no Thai name. */
+  name: z.object({
+    en: z.string().trim().min(1, "the business needs a name").max(200),
+    th: z.string().trim().min(1).max(200).nullable()
+  }),
+  /** Head-office address as one block of text; null until someone enters it. */
+  headOfficeAddress: z.string().trim().min(1).max(1e3).nullable(),
+  /** Tax ID; null for a business with none (under the VAT threshold, say). */
+  taxId: z.string().trim().min(1).max(40).nullable(),
+  /** ISO 3166-1 alpha-2. */
+  country: z.string().regex(/^[A-Z]{2}$/, "country is an ISO 3166-1 alpha-2 code"),
+  /** ISO 4217. */
+  currency: z.string().regex(/^[A-Z]{3}$/, "currency is an ISO 4217 code"),
+  /** IANA time zone. */
+  timezone: z.string().refine(isIanaTimeZone, "timezone is not an IANA time zone")
+});
 var CONTROLS = {
   "flag.paymentsSetupStep": { schema: z.boolean(), appWrite: false },
   "plan.locations": {
@@ -37,7 +64,13 @@ var CONTROLS = {
   "plan.accountingEdition": {
     schema: z.enum(["small", "medium"]).nullable(),
     appWrite: false
-  }
+  },
+  /**
+   * The business this app is for, owned by Stardeck. null means Stardeck has no record yet: an
+   * app that already has its own company details sends them up once. `{ ok: false }` means
+   * unknown right now: keep the company the app has.
+   */
+  "business.profile": { schema: businessProfileSchema.nullable(), appWrite: true }
 };
 var CONTROL_KEYS = Object.keys(CONTROLS);
 function parseOne(entry, schema) {

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@stardeck-customer-apps/controls",
   "type": "module",
-  "version": "0.3.0",
+  "version": "0.4.0",
   "description": "Platform-owned app controls (feature flags, plan limits, POS Pro hardware, the Accounting edition, 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",