esoul-sdk 0.7.0 → 0.8.0

package/README.md

@@ -160,6 +160,15 @@ something: does the write survive?
 
 ## Versions
 
+- **0.8.0** — the three things making an app LOOK like a product turned out to
+  need: `generateAppImage` (one call — generates, brings the bytes to web
+  weight, hands back an https URL; a 2.4 MB PNG is not a page), `setAppRole` /
+  `listAppRoles` (an owner gives one esoul account one of your role words, by
+  email; the platform does every check and records it on the app's timeline),
+  and `wall.ask()` — attempt a read and let a `login-required` refusal answer,
+  because `viewer.signedIn` is this page's guess and can disagree with the
+  session your ops run under. An app that gated on the guess showed a
+  signed-in shopper a sign-in wall over a full basket.
 - **0.7.0** — what a catalogue-sized app needs. **Index kinds**: a plain group is a btree,
   `{ fields: ["tags"], kind: "contains" }` answers `{ tags: { has: … } }` on a list, and
   `{ fields: ["title"], kind: "text" }` answers `{ title: { contains: … } }` — so a department

package/dist/server.d.ts

@@ -222,6 +222,97 @@ export declare function pluginDb<T = unknown>(_ctx: {
     across?: "owned-instances" | "my-rows";
     viaBinding?: boolean;
 }): Promise<T>;
+/**
+ * A PICTURE FOR YOUR APP, FROM ONE CALL.
+ *
+ * Generates an image, brings it to web weight and returns an **https URL** to
+ * store on your own row and render. You do not choose a model, resize
+ * anything, or know where the bytes live.
+ *
+ *   const pic = await generateAppImage(ctx, {
+ *     name: product.sku ?? product.id,
+ *     prompt: "A small dish of loose-leaf black tea beside a glass cup of amber tea.",
+ *     // the SAME style for every picture in the app, so a shelf looks
+ *     // photographed on one table instead of bought from a library:
+ *     style: "On warm oatmeal linen, soft window light from the left, shallow depth of field.",
+ *     shape: "square",
+ *   });
+ *   if (pic.ok) await db.product.update({ where: { id }, data: { imageUrl: pic.url } });
+ *
+ * A refusal comes back as `{ ok: false, error }` naming every provider that
+ * said no — an account denied by one and unkeyed for another are different
+ * problems. Flat, so an app compiled with `strict: false` can read it.
+ *
+ * HOST-ONLY. It spends money; keep it behind an op only the owner may call.
+ */
+export declare function generateAppImage(_ctx: {
+    pluginId: string;
+    nodeId: string;
+}, _args: {
+    name: string;
+    prompt: string;
+    style?: string;
+    shape?: "square" | "wide" | "tall";
+}): Promise<GeneratedAppImage>;
+export interface GeneratedAppImage {
+    ok: boolean;
+    /** Store this on your row and put it in an `img src`. */
+    url?: string;
+    bytes?: number;
+    model?: string;
+    error?: string;
+}
+/**
+ * WHO ELSE MAY USE THIS INSTANCE, AND AS WHAT.
+ *
+ * Your app declares its own role words (`roles.vocabulary`), and the owner can
+ * hand one to another esoul account by EMAIL. The platform does all of it: it
+ * checks the caller owns the app, resolves the email against a real account
+ * once, refuses a role your manifest never declared, and records the grant on
+ * this instance's own timeline — so your op is a pass-through and your app
+ * cannot forge a grant.
+ *
+ * `role: ""` takes it back. The next time that person opens the app,
+ * `ctx.viewer.role` is the word you gave them, and your `db` rules decide the
+ * rest. It does NOT make them a writer of the workspace: a grant changes your
+ * app's word for someone, never the platform's capabilities.
+ *
+ * HOST-ONLY.
+ */
+export declare function setAppRole(_ctx: {
+    pluginId: string;
+    workspaceId: string;
+    nodeId: string;
+    viewer: PluginViewer;
+}, _args: {
+    email: string;
+    role: string;
+}): Promise<AppRoleResult>;
+/** Everyone the owner has given a role in THIS instance. HOST-ONLY. */
+export declare function listAppRoles(_ctx: {
+    pluginId: string;
+    workspaceId: string;
+    nodeId: string;
+    viewer: PluginViewer;
+}): Promise<{
+    people: AppRolePerson[];
+    roles: string[];
+}>;
+export interface AppRolePerson {
+    userId: string;
+    /** As the owner typed it, for the screen. Never what is checked. */
+    email: string | null;
+    role: string;
+    grantedAt?: number;
+}
+/** Flat, not a discriminated union: an app compiled with `strict: false` cannot narrow one. */
+export interface AppRoleResult {
+    ok: boolean;
+    userId?: string;
+    email?: string;
+    role?: string;
+    error?: string;
+}
 export interface EmitPluginAppEventArgs {
     source: {
         pluginId: string;

package/dist/server.js

@@ -46,6 +46,56 @@ export function getPluginConnectionCredentials(_connectionId, _pluginId) {
 export function pluginDb(_ctx, _reach) {
     return hostOnly("pluginDb");
 }
+/**
+ * A PICTURE FOR YOUR APP, FROM ONE CALL.
+ *
+ * Generates an image, brings it to web weight and returns an **https URL** to
+ * store on your own row and render. You do not choose a model, resize
+ * anything, or know where the bytes live.
+ *
+ *   const pic = await generateAppImage(ctx, {
+ *     name: product.sku ?? product.id,
+ *     prompt: "A small dish of loose-leaf black tea beside a glass cup of amber tea.",
+ *     // the SAME style for every picture in the app, so a shelf looks
+ *     // photographed on one table instead of bought from a library:
+ *     style: "On warm oatmeal linen, soft window light from the left, shallow depth of field.",
+ *     shape: "square",
+ *   });
+ *   if (pic.ok) await db.product.update({ where: { id }, data: { imageUrl: pic.url } });
+ *
+ * A refusal comes back as `{ ok: false, error }` naming every provider that
+ * said no — an account denied by one and unkeyed for another are different
+ * problems. Flat, so an app compiled with `strict: false` can read it.
+ *
+ * HOST-ONLY. It spends money; keep it behind an op only the owner may call.
+ */
+export function generateAppImage(_ctx, _args) {
+    return hostOnly("generateAppImage");
+}
+/**
+ * WHO ELSE MAY USE THIS INSTANCE, AND AS WHAT.
+ *
+ * Your app declares its own role words (`roles.vocabulary`), and the owner can
+ * hand one to another esoul account by EMAIL. The platform does all of it: it
+ * checks the caller owns the app, resolves the email against a real account
+ * once, refuses a role your manifest never declared, and records the grant on
+ * this instance's own timeline — so your op is a pass-through and your app
+ * cannot forge a grant.
+ *
+ * `role: ""` takes it back. The next time that person opens the app,
+ * `ctx.viewer.role` is the word you gave them, and your `db` rules decide the
+ * rest. It does NOT make them a writer of the workspace: a grant changes your
+ * app's word for someone, never the platform's capabilities.
+ *
+ * HOST-ONLY.
+ */
+export function setAppRole(_ctx, _args) {
+    return hostOnly("setAppRole");
+}
+/** Everyone the owner has given a role in THIS instance. HOST-ONLY. */
+export function listAppRoles(_ctx) {
+    return hostOnly("listAppRoles");
+}
 /**
  * Cross-app events: dispatch the TARGET app's own events through the
  * platform spine (target's dataCreator mints; triggers fire; every event is

package/docs/05-ui.md

@@ -114,3 +114,31 @@ installed, only the grants in `plugin.json` `workspaceTools` are allowed. Declar
 The platform is built as craft: a sticky-notes wall is linen and paper with a gummed strip, not a
 grid of yellow rectangles. Derive any randomness from stable ids, never `Math.random()` in
 render, so nothing twitches between renders. Motion is brief and respects reduced-motion.
+
+## Pictures
+
+`generateAppImage` is one call: it generates, brings the bytes to web weight and
+returns an **https URL** to store on your own row.
+
+```ts
+const pic = await generateAppImage(ctx, {
+  name: product.sku ?? product.id,
+  prompt: "A small dish of loose-leaf black tea beside a glass cup of amber tea.",
+  // THE SAME style for every picture in the app. This is what makes a shelf
+  // look photographed on one table instead of bought from a library.
+  style: "On warm oatmeal linen, soft window light from the left, shallow depth of field.",
+  shape: "square",                       // or "wide" for a hero, "tall"
+});
+if (pic.ok) await db.product.update({ where: { id }, data: { imageUrl: pic.url } });
+```
+
+It costs real money, so keep it behind an op only the owner may call. A
+workbench refuses it on purpose — a preview that billed on every hot reload
+would be a bad surprise, and one that returned a fake URL a worse one.
+
+**Draw the empty case first.** A generated picture is the second version of a
+screen; the first is the one with no picture at all, which is what every app
+looks like on the day it is installed. An `aspect-square` box with a small
+inline SVG pattern and the thing's icon reads as "not photographed yet"; a grey
+rectangle reads as broken. Fix the aspect ratio in both branches and nothing
+moves when a photograph arrives.

package/docs/13-people-and-access.md

@@ -150,3 +150,47 @@ record" but "does the OTHER one see it".
 
 `look_at_app` takes the same personas, so you can photograph the screen each of them gets — the
 one screen an author can otherwise never see, because the author is always the owner.
+
+## Who has an account: ASK, never assume
+
+`viewer.signedIn` is the platform's guess from THIS PAGE's capabilities. On a
+shared link it can disagree with the session your ops actually run under — so
+an app that gates its reads on it shows a signed-in person an empty basket and
+a sign-in wall while the server is holding their order. That is a real bug, seen
+on a real shop.
+
+So never gate a read. Attempt it, and let the refusal answer:
+
+```tsx
+const wall = useSignInWall();
+
+const load = useCallback(() => {
+  // `ask` runs the call whatever this page believes, and hands back `null`
+  // when the SERVER says there is no account — which also raises the wall.
+  wall.ask<Cart>(() => callPluginOp(PLUGIN_ID, "view-cart", nodeId)).then((c) => c && setCart(c));
+}, [wall, nodeId]);
+```
+
+`wall.serverSays` is `null` until the server answers, then `"account"` or
+`"no-account"`. Use `viewer.signedIn` for WORDING if you like (it saves a
+flicker) and `serverSays` for anything that hides a screen. And if you hold
+data the server already gave you — lines in a basket — show it: a wall over a
+full basket is never right.
+
+## Giving one person access to one app
+
+An owner can hand another esoul account one of YOUR role words, by email:
+
+```ts
+const r = await setAppRole(ctx, { email: "helper@example.com", role: "staff" });
+if (!r.ok) throw new Error(r.error);      // "no esoul account has that email"
+const { people, roles } = await listAppRoles(ctx);
+```
+
+The platform does the deciding: only the app's owner may call it, the email is
+resolved once against a real (non-guest) account, and the role must be one your
+manifest declares. The grant lands on this instance's own timeline, so it can be
+read back, explained and scrubbed. Next time that person opens the app,
+`ctx.viewer.role` is the word you gave them and your `db` rules do the rest —
+it does not make them a writer of the workspace, and it can never demote the
+owner.

package/llms-full.txt

@@ -164,6 +164,15 @@ something: does the write survive?
 
 ## Versions
 
+- **0.8.0** — the three things making an app LOOK like a product turned out to
+  need: `generateAppImage` (one call — generates, brings the bytes to web
+  weight, hands back an https URL; a 2.4 MB PNG is not a page), `setAppRole` /
+  `listAppRoles` (an owner gives one esoul account one of your role words, by
+  email; the platform does every check and records it on the app's timeline),
+  and `wall.ask()` — attempt a read and let a `login-required` refusal answer,
+  because `viewer.signedIn` is this page's guess and can disagree with the
+  session your ops run under. An app that gated on the guess showed a
+  signed-in shopper a sign-in wall over a full basket.
 - **0.7.0** — what a catalogue-sized app needs. **Index kinds**: a plain group is a btree,
   `{ fields: ["tags"], kind: "contains" }` answers `{ tags: { has: … } }` on a list, and
   `{ fields: ["title"], kind: "text" }` answers `{ title: { contains: … } }` — so a department
@@ -668,6 +677,34 @@ The platform is built as craft: a sticky-notes wall is linen and paper with a gu
 grid of yellow rectangles. Derive any randomness from stable ids, never `Math.random()` in
 render, so nothing twitches between renders. Motion is brief and respects reduced-motion.
 
+## Pictures
+
+`generateAppImage` is one call: it generates, brings the bytes to web weight and
+returns an **https URL** to store on your own row.
+
+```ts
+const pic = await generateAppImage(ctx, {
+  name: product.sku ?? product.id,
+  prompt: "A small dish of loose-leaf black tea beside a glass cup of amber tea.",
+  // THE SAME style for every picture in the app. This is what makes a shelf
+  // look photographed on one table instead of bought from a library.
+  style: "On warm oatmeal linen, soft window light from the left, shallow depth of field.",
+  shape: "square",                       // or "wide" for a hero, "tall"
+});
+if (pic.ok) await db.product.update({ where: { id }, data: { imageUrl: pic.url } });
+```
+
+It costs real money, so keep it behind an op only the owner may call. A
+workbench refuses it on purpose — a preview that billed on every hot reload
+would be a bad surprise, and one that returned a fake URL a worse one.
+
+**Draw the empty case first.** A generated picture is the second version of a
+screen; the first is the one with no picture at all, which is what every app
+looks like on the day it is installed. An `aspect-square` box with a small
+inline SVG pattern and the thing's icon reads as "not photographed yet"; a grey
+rectangle reads as broken. Fix the aspect ratio in both branches and nothing
+moves when a photograph arrives.
+
 
 
 ==============================================================================
@@ -1367,6 +1404,50 @@ record" but "does the OTHER one see it".
 `look_at_app` takes the same personas, so you can photograph the screen each of them gets — the
 one screen an author can otherwise never see, because the author is always the owner.
 
+## Who has an account: ASK, never assume
+
+`viewer.signedIn` is the platform's guess from THIS PAGE's capabilities. On a
+shared link it can disagree with the session your ops actually run under — so
+an app that gates its reads on it shows a signed-in person an empty basket and
+a sign-in wall while the server is holding their order. That is a real bug, seen
+on a real shop.
+
+So never gate a read. Attempt it, and let the refusal answer:
+
+```tsx
+const wall = useSignInWall();
+
+const load = useCallback(() => {
+  // `ask` runs the call whatever this page believes, and hands back `null`
+  // when the SERVER says there is no account — which also raises the wall.
+  wall.ask<Cart>(() => callPluginOp(PLUGIN_ID, "view-cart", nodeId)).then((c) => c && setCart(c));
+}, [wall, nodeId]);
+```
+
+`wall.serverSays` is `null` until the server answers, then `"account"` or
+`"no-account"`. Use `viewer.signedIn` for WORDING if you like (it saves a
+flicker) and `serverSays` for anything that hides a screen. And if you hold
+data the server already gave you — lines in a basket — show it: a wall over a
+full basket is never right.
+
+## Giving one person access to one app
+
+An owner can hand another esoul account one of YOUR role words, by email:
+
+```ts
+const r = await setAppRole(ctx, { email: "helper@example.com", role: "staff" });
+if (!r.ok) throw new Error(r.error);      // "no esoul account has that email"
+const { people, roles } = await listAppRoles(ctx);
+```
+
+The platform does the deciding: only the app's owner may call it, the email is
+resolved once against a real (non-guest) account, and the role must be one your
+manifest declares. The grant lands on this instance's own timeline, so it can be
+read back, explained and scrubbed. Next time that person opens the app,
+`ctx.viewer.role` is the word you gave them and your `db` rules do the rest —
+it does not make them a writer of the workspace, and it can never demote the
+owner.
+
 
 
 ==============================================================================

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "esoul-sdk",
-  "version": "0.7.0",
+  "version": "0.8.0",
   "description": "Build a full product on ExternalSoul: your own tables with per-person rules, a viewer on every seam, app roles, access levels, realtime with audiences, durable tasks, and bindings to other apps.",
   "license": "UNLICENSED",
   "type": "module",