@stardeck-customer-apps/controls 0.4.0 → 0.5.0

package/SKILL.md

@@ -55,6 +55,7 @@ the last values stay.
 | `payments.provider`      | `"beam" \| "stripe" \| null`                                                                    | yes           |
 | `payments.methods`       | `{ card: boolean, promptPay: boolean }`                                                         | yes           |
 | `business.profile`       | `BusinessProfile \| null` (see "Business details")                                              | yes           |
+| `business.logo`          | `{ url: string } \| null` (see "Business logo")                                                 | no            |
 
 - `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
@@ -68,6 +69,8 @@ the last values stay.
 - `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.
+- `business.logo` is the organization's logo (controls 0.5.0 or later). `null`
+  means it has none. See "Business logo" below.
 - Keys are never removed in later versions, so code written against today's list
   keeps working.
 
@@ -168,6 +171,24 @@ if (!parsed.success) return badRequest(parsed.error.issues[0]?.message);
 const result = await setControl("business.profile", parsed.data, { userToken });
 ```
 
+## Business logo
+
+The organization's logo is the icon it set on Stardeck (onboarding asks for
+one). It is the default logo for every app in the organization (needs controls
+0.5.0 or later). Show it wherever the app shows a logo and has none of its own:
+the site header, the admin shell, emails, receipts. When the owner uploads a
+logo in the app, that one wins for this app; never copy the organization's logo
+into the app's own setting, or a later change on Stardeck won't reach it.
+
+```ts
+const orgLogo = await getControl("business.logo");
+// ok: false is "unknown right now": show the app's own logo, or none, and never fail.
+const logoUrl = appLogoUrl ?? (orgLogo.ok ? (orgLogo.value?.url ?? null) : null);
+```
+
+The URL is an https image Stardeck's sign-in provider hosts. It is read-only:
+`setControl("business.logo", …)` is refused with `NOT_WRITABLE`.
+
 Types and the list itself are in the root export:
 
 ```ts

package/dist/index.cjs

@@ -102,7 +102,16 @@ var CONTROLS = {
    * 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 }
+  "business.profile": { schema: businessProfileSchema.nullable(), appWrite: true },
+  /**
+   * The org's logo: the icon it set in Stardeck (onboarding asks for one). The app shows it
+   * wherever it has no logo of its own, and an owner's own upload always wins. null means the
+   * org has no logo. Read-only: the app changes its own logo, never the org's.
+   */
+  "business.logo": {
+    schema: import_zod.z.object({ url: import_zod.z.string().url().startsWith("https://", "the logo is served over https") }).nullable(),
+    appWrite: false
+  }
 };
 var CONTROL_KEYS = Object.keys(CONTROLS);
 function isControlKey(key) {

package/dist/index.d.cts

@@ -104,6 +104,17 @@ declare const CONTROLS: {
         }, z.core.$strip>>;
         readonly appWrite: true;
     };
+    /**
+     * The org's logo: the icon it set in Stardeck (onboarding asks for one). The app shows it
+     * wherever it has no logo of its own, and an owner's own upload always wins. null means the
+     * org has no logo. Read-only: the app changes its own logo, never the org's.
+     */
+    readonly "business.logo": {
+        readonly schema: z.ZodNullable<z.ZodObject<{
+            url: z.ZodString;
+        }, z.core.$strip>>;
+        readonly appWrite: false;
+    };
 };
 type ControlKey = keyof typeof CONTROLS;
 type ControlValue<K extends ControlKey> = z.infer<(typeof CONTROLS)[K]["schema"]>;

package/dist/index.d.ts

@@ -104,6 +104,17 @@ declare const CONTROLS: {
         }, z.core.$strip>>;
         readonly appWrite: true;
     };
+    /**
+     * The org's logo: the icon it set in Stardeck (onboarding asks for one). The app shows it
+     * wherever it has no logo of its own, and an owner's own upload always wins. null means the
+     * org has no logo. Read-only: the app changes its own logo, never the org's.
+     */
+    readonly "business.logo": {
+        readonly schema: z.ZodNullable<z.ZodObject<{
+            url: z.ZodString;
+        }, z.core.$strip>>;
+        readonly appWrite: false;
+    };
 };
 type ControlKey = keyof typeof CONTROLS;
 type ControlValue<K extends ControlKey> = z.infer<(typeof CONTROLS)[K]["schema"]>;

package/dist/index.js

@@ -70,7 +70,16 @@ var CONTROLS = {
    * 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 }
+  "business.profile": { schema: businessProfileSchema.nullable(), appWrite: true },
+  /**
+   * The org's logo: the icon it set in Stardeck (onboarding asks for one). The app shows it
+   * wherever it has no logo of its own, and an owner's own upload always wins. null means the
+   * org has no logo. Read-only: the app changes its own logo, never the org's.
+   */
+  "business.logo": {
+    schema: z.object({ url: z.string().url().startsWith("https://", "the logo is served over https") }).nullable(),
+    appWrite: false
+  }
 };
 var CONTROL_KEYS = Object.keys(CONTROLS);
 function isControlKey(key) {

package/dist/server/index.cjs

@@ -102,7 +102,16 @@ var CONTROLS = {
    * 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 }
+  "business.profile": { schema: businessProfileSchema.nullable(), appWrite: true },
+  /**
+   * The org's logo: the icon it set in Stardeck (onboarding asks for one). The app shows it
+   * wherever it has no logo of its own, and an owner's own upload always wins. null means the
+   * org has no logo. Read-only: the app changes its own logo, never the org's.
+   */
+  "business.logo": {
+    schema: import_zod.z.object({ url: import_zod.z.string().url().startsWith("https://", "the logo is served over https") }).nullable(),
+    appWrite: false
+  }
 };
 var CONTROL_KEYS = Object.keys(CONTROLS);
 function parseOne(entry, schema) {

package/dist/server/index.d.cts

@@ -86,6 +86,17 @@ declare const CONTROLS: {
         }, z.core.$strip>>;
         readonly appWrite: true;
     };
+    /**
+     * The org's logo: the icon it set in Stardeck (onboarding asks for one). The app shows it
+     * wherever it has no logo of its own, and an owner's own upload always wins. null means the
+     * org has no logo. Read-only: the app changes its own logo, never the org's.
+     */
+    readonly "business.logo": {
+        readonly schema: z.ZodNullable<z.ZodObject<{
+            url: z.ZodString;
+        }, z.core.$strip>>;
+        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

@@ -86,6 +86,17 @@ declare const CONTROLS: {
         }, z.core.$strip>>;
         readonly appWrite: true;
     };
+    /**
+     * The org's logo: the icon it set in Stardeck (onboarding asks for one). The app shows it
+     * wherever it has no logo of its own, and an owner's own upload always wins. null means the
+     * org has no logo. Read-only: the app changes its own logo, never the org's.
+     */
+    readonly "business.logo": {
+        readonly schema: z.ZodNullable<z.ZodObject<{
+            url: z.ZodString;
+        }, z.core.$strip>>;
+        readonly appWrite: false;
+    };
 };
 type ControlKey = keyof typeof CONTROLS;
 type ControlValue<K extends ControlKey> = z.infer<(typeof CONTROLS)[K]["schema"]>;

package/dist/server/index.js

@@ -70,7 +70,16 @@ var CONTROLS = {
    * 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 }
+  "business.profile": { schema: businessProfileSchema.nullable(), appWrite: true },
+  /**
+   * The org's logo: the icon it set in Stardeck (onboarding asks for one). The app shows it
+   * wherever it has no logo of its own, and an owner's own upload always wins. null means the
+   * org has no logo. Read-only: the app changes its own logo, never the org's.
+   */
+  "business.logo": {
+    schema: z.object({ url: z.string().url().startsWith("https://", "the logo is served over https") }).nullable(),
+    appWrite: false
+  }
 };
 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.4.0",
+  "version": "0.5.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",