@stardeck-customer-apps/controls 0.1.0 → 0.3.0

package/SKILL.md

@@ -3,8 +3,9 @@
 **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, 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
@@ -48,15 +49,73 @@ 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           |
 
 - `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.
 - 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"
+```
+
 Types and the list itself are in the root export:
 
 ```ts

package/dist/index.cjs

@@ -52,6 +52,22 @@ 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
   }
 };
 var CONTROL_KEYS = Object.keys(CONTROLS);

package/dist/index.d.cts

@@ -48,6 +48,24 @@ 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;
+    };
 };
 type ControlKey = keyof typeof CONTROLS;
 type ControlValue<K extends ControlKey> = z.infer<(typeof CONTROLS)[K]["schema"]>;

package/dist/index.d.ts

@@ -48,6 +48,24 @@ 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;
+    };
 };
 type ControlKey = keyof typeof CONTROLS;
 type ControlValue<K extends ControlKey> = z.infer<(typeof CONTROLS)[K]["schema"]>;

package/dist/index.js

@@ -21,6 +21,22 @@ 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
   }
 };
 var CONTROL_KEYS = Object.keys(CONTROLS);

package/dist/server/index.cjs

@@ -53,6 +53,22 @@ 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
   }
 };
 var CONTROL_KEYS = Object.keys(CONTROLS);

package/dist/server/index.d.cts

@@ -48,6 +48,24 @@ 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;
+    };
 };
 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,24 @@ 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;
+    };
 };
 type ControlKey = keyof typeof CONTROLS;
 type ControlValue<K extends ControlKey> = z.infer<(typeof CONTROLS)[K]["schema"]>;

package/dist/server/index.js

@@ -21,6 +21,22 @@ 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
   }
 };
 var CONTROL_KEYS = Object.keys(CONTROLS);

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.3.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",