@stardeck-customer-apps/controls 0.1.0 → 0.4.0

package/SKILL.md

@@ -3,8 +3,10 @@
 **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.
+flags, what the plan allows, how many locations have POS Pro hardware, which
+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
@@ -48,15 +50,124 @@ the last values stay.
 | `flag.paymentsSetupStep` | `boolean`                                                                                       | no            |
 | `plan.locations`         | `{ included: number \| null, max: number \| null, extraMonthly: { amount, currency } \| null }` | no            |
 | `plan.multiEntity`       | `boolean`                                                                                       | no            |
+| `pos.pro`                | `{ locations: number \| null }`                                                                 | no            |
+| `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
   billed at `extraMonthly`. `included: null` means the number was agreed per deal.
+- `pos.pro.locations` is how many locations the business pays for POS Pro (Edge
+  receipt printing, Bolt+ card terminals). `null` means no limit; `0` means none
+  (the entry plan never includes POS Pro). See "POS Pro hardware" below.
+- `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.
 
+## POS Pro hardware
+
+Check `pos.pro` only when someone adds POS hardware (pairs a receipt printer or
+a card terminal) at a location that has none yet. Never check it on a sale, a
+print or a payment: hardware that is already set up keeps working whatever the
+count says, so a business is never stopped mid-service.
+
+```ts
+const posPro = await getControl("pos.pro");
+if (!posPro.ok) {
+  // Unknown right now: refuse the add with a retry message (answer 503), and
+  // leave the hardware the business already has alone.
+  return unavailable("POS Pro could not be checked. Try again in a minute.");
+}
+const { locations } = posPro.value;
+const usesPosPro = await countLocationsWithPosHardware(); // locations with a printer or terminal
+if (locations !== null && !locationAlreadyHasHardware && usesPosPro >= locations) {
+  return refuse("Every POS Pro location you pay for is in use. Add POS Pro to this location first.");
+}
+```
+
+A location that already has a printer or terminal can add more without using up
+another POS Pro location.
+
+## Accounting edition
+
+Accounting comes in two editions, Small and Medium, each bought as an add-on.
+Finance is on every plan and never depends on this control. Read
+`plan.accountingEdition` to decide which Accounting the app offers:
+
+- `"small"` or `"medium"`: offer that edition.
+- `null`: the business has no Accounting plan. Hide Accounting and refuse its
+  writes with a message that it needs an Accounting plan. Records it made while
+  it had one stay readable.
+- `ok: false`: unknown right now, which is not the same as `null`. Refuse new
+  accounting records (journal entries, period closes, filings) with a retry
+  message (answer 503), and keep everything that exists readable. Never hide
+  Accounting or treat the business as having none because of `ok: false`.
+
+```ts
+const edition = await getControl("plan.accountingEdition");
+if (!edition.ok) {
+  return unavailable("Accounting could not be checked. Try again in a minute.");
+}
+if (edition.value === null) {
+  return refuse("Accounting needs an Accounting plan.");
+}
+// 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
@@ -65,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": {
@@ -52,7 +80,29 @@ var CONTROLS = {
   "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
+  },
+  /**
+   * 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) {
@@ -98,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.
  *
@@ -48,6 +66,44 @@ declare const CONTROLS: {
         }, 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;
+    };
+    /**
+     * 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"]>;
@@ -100,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.
  *
@@ -48,6 +66,44 @@ declare const CONTROLS: {
         }, 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;
+    };
+    /**
+     * 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"]>;
@@ -100,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": {
@@ -21,7 +48,29 @@ var CONTROLS = {
   "payments.methods": {
     schema: z.object({ card: z.boolean(), promptPay: z.boolean() }),
     appWrite: true
-  }
+  },
+  "pos.pro": {
+    schema: z.object({
+      /** POS Pro locations paid for. null = unlimited (legacy plans, internal orgs). */
+      locations: 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: 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) {
@@ -66,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": {
@@ -53,7 +80,29 @@ var CONTROLS = {
   "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
+  },
+  /**
+   * 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

@@ -48,6 +48,44 @@ declare const CONTROLS: {
         }, 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;
+    };
+    /**
+     * 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

@@ -48,6 +48,44 @@ declare const CONTROLS: {
         }, 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;
+    };
+    /**
+     * 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": {
@@ -21,7 +48,29 @@ var CONTROLS = {
   "payments.methods": {
     schema: z.object({ card: z.boolean(), promptPay: z.boolean() }),
     appWrite: true
-  }
+  },
+  "pos.pro": {
+    schema: z.object({
+      /** POS Pro locations paid for. null = unlimited (legacy plans, internal orgs). */
+      locations: 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: 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,8 +1,8 @@
 {
   "name": "@stardeck-customer-apps/controls",
   "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",
+  "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",
   "types": "dist/index.d.ts",