@uidu/skills 0.3.0 → 0.4.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@uidu/skills",
-  "version": "0.3.0",
+  "version": "0.4.0",
   "description": "Agent skills for the uidu SDK — installable via the open agent skills ecosystem (skills.sh).",
   "license": "MIT",
   "author": "uidu",

package/skills/uidu/SKILL.md

@@ -1,18 +1,19 @@
 ---
 name: uidu
-description: Use when building on the uidu platform — reading CMS pages, events, stories, donations, help center, forms; rendering WYSIWYG content; scaffolding projects; OR provisioning/authoring uidu content (create/update/delete) from the terminal via the @uidu/cli (`uidu`). Triggers on any task involving uidu, the @uidu/client SDK, @uidu/react bindings, or the uidu CLI.
+description: Use when building on the uidu platform — a public website or an app that runs inside uidu (a custom app in a Space or workspace); reading CMS pages, events, stories, donations, help center, forms; rendering WYSIWYG content; scaffolding projects; OR provisioning/authoring uidu content (create/update/delete) from the terminal via the @uidu/cli (`uidu`). Triggers on any task involving uidu, the @uidu/client SDK, @uidu/react bindings, or the uidu CLI.
 license: MIT
 metadata:
   author: uidu
-  version: "0.3.0"
+  version: "0.5.0"
 ---
 
 # uidu SDK
 
-The uidu SDK is a TypeScript GraphQL toolkit for building websites and apps powered by the uidu platform. It is split into two packages:
+The uidu SDK is a TypeScript GraphQL toolkit for building websites and apps powered by the uidu platform. It is split into three packages:
 
 - **`@uidu/client`** — framework-agnostic GraphQL client. Safe for server-side use (RSC, route handlers, server actions, scripts).
-- **`@uidu/react`** — React hooks (`useFields`, `useQuery`, `useForm`, `useChannel`) and components (`<PageBlocks>`, `<RichText>`).
+- **`@uidu/app-bridge`** — the browser half of a custom app: the handshake with the uidu page that frames it, and its short-lived session token. Only for apps that run inside uidu.
+- **`@uidu/react`** — React hooks (`useUiduClient`, `useQuery`, `useFields`, `toText`, `useUiduApp`) and components (`<UiduAppProvider>`, `<PageBlocks>`, `<BlockRenderer>`, `<RichText>`, `<DynamicForm>`). That list is the **complete** public surface — there is no `useForm`, `usePage` or `useChannel`; for anything else, call a `@uidu/client` function.
 
 `@uidu/api.js` is a legacy bridge package and is **deprecated** — use `@uidu/react` directly.
 
@@ -20,7 +21,7 @@ The uidu SDK is a TypeScript GraphQL toolkit for building websites and apps powe
 
 Use this skill when the user is:
 
-- Building a Next.js / Remix / Astro / React app powered by the uidu GraphQL API
+- Building a Next.js / Remix / Astro / React app powered by the uidu GraphQL API — a public site, or a **custom app** that uidu shows inside a Space or workspace to signed-in members (same stack, different auth: see the rule below)
 - Fetching CMS pages, events, blog stories, donation campaigns, or help center content
 - Rendering uidu blocks with `<PageBlocks>` and a component map
 - Rendering WYSIWYG body fields with `<RichText>`
@@ -34,6 +35,7 @@ Use this skill when the user is:
 |---|---|---|
 | `@uidu/client` | Server-side queries (RSC, server actions, scripts) | Framework-agnostic |
 | `@uidu/react` | React hooks, providers, and components | Some hooks are client-only |
+| `@uidu/app-bridge` | An app that runs inside uidu (custom app) | Browser only; in React use `<UiduAppProvider>` |
 | `@uidu/api.js` | **Do not use for new code.** | Deprecated; re-exports `@uidu/react` |
 
 Install:
@@ -76,18 +78,97 @@ bookings, calls, campaigns, kb-collections, kb-articles, channel` (read) and
 reports `does not support <verb>` when it doesn't. Config resolves **flags → env
 (`UIDU_*`) → `~/.uidu/config.json`** (written by `uidu login`).
 
-## Reading vs writing — one rule
+## Who the app acts for — one rule
+
+What an app *looks like* (landing page, blog, dashboard, booking tool) changes nothing.
+What changes the code is **who the request acts for**:
 
 | Operation | Auth | Where it runs |
 |---|---|---|
-| **Reads** (`get*` / `list*`, `<entity> list/get`) | `publicToken` | anywhere — server, CLI, **and the browser** |
-| **Writes** (`create*` / `update*` / `delete*`, `<entity> create/update/delete`) | account **Bearer** (`apiKey`) | CLI and **server-side** only |
+| **Reads** for anyone (`get*` / `list*`, `<entity> list/get`) | `publicToken` | anywhere — server, CLI, **and the browser** |
+| **Writes** as the workspace (`create*` / `update*` / `delete*`, `<entity> create/update/delete`) | account **Bearer** (`apiKey`) | CLI and **server-side** only |
+| **Anything as the signed-in member**, inside uidu (a custom app) | session token from the host, over `@uidu/app-bridge` | **the browser only** |
 
 The write functions live in `@uidu/client`, so anything the CLI provisions you can also do
 from a Next.js server action / route handler / RSC. **Never put the account Bearer token in a
 browser client component.** Authoring mutations return a payload with an `errors` array —
 always check it (non-empty = validation failure).
 
+One app can mix the rows: public pages rendered on the server with `publicToken`, and a members'
+area that only works when uidu frames it.
+
+### Inside uidu: the third row
+
+uidu renders a custom app in a sandboxed iframe and hands it a short-lived session (5 minutes,
+refreshed by the bridge) over `postMessage`. That session is the member's: the app can do what
+that person can do, and no more. It changes five things:
+
+1. **The token only exists in the browser.** It arrives after the page loads, so a Server
+   Component or a server action never has it. Pages that show member data are `'use client'`
+   and read through the bridge-backed client. Fetching them in an RSC renders an empty page.
+2. **The token only works from the app's own origin.** uidu checks `Origin` against the origin
+   it signed the token for. Don't forward it to your own backend to call uidu from there — that
+   needs a server credential uidu doesn't issue yet.
+3. **Treat the token as opaque.** Never decode it. The expiry comes with it, the bridge refreshes
+   it, and `graphqlUrl` comes with it too: never build `https://<workspace>.uidu.org` from a slug.
+4. **Data goes in the app's own Models.** The session reaches the app's own Models, fields and
+   items through `node(id:)`, and the data-engine mutations. Everything else in the workspace comes
+   back as an error. Keep your data there rather than in a database of your own: it stays
+   searchable and permissioned in uidu.
+   `listModelItems` reads uidu's **search index**, which catches up a moment after a write:
+   after `createModelItem` / `deleteModelItem`, update your list from the mutation payload
+   instead of re-listing, or the new item is missing. And load models once per app instance
+   (memoize the promise): two concurrent `ensureModel` calls each create the model.
+5. **No cookies, no `localStorage` for shared state.** In a cross-origin iframe cookies are
+   third-party (Safari drops them). `localStorage` is this browser only. Use it only as the
+   fallback when the page is opened outside uidu (the bridge rejects `connect()` there).
+
+```tsx
+'use client'; // app/layout.tsx renders <AppProvider> around {children}
+import { useEffect, useState } from 'react';
+import { UiduAppProvider, useUiduApp } from '@uidu/react';
+import { DEFAULT_HOST_ORIGINS } from '@uidu/app-bridge';
+import {
+  createModelItem, ensureModel, listModelItems, toFieldValuesAttributes,
+  type ModelItem, type UiduClient,
+} from '@uidu/client';
+
+export function AppProvider({ children }: { children: React.ReactNode }) {
+  // https://*.uidu.org by default; add a local uidu or a custom domain
+  return <UiduAppProvider hostOrigins={[...DEFAULT_HOST_ORIGINS]}>{children}</UiduAppProvider>;
+}
+
+async function loadBookings(client: UiduClient, workspaceAppId: string) {
+  // interim: the app creates its own model on first load (install-time manifest comes later)
+  const model = await ensureModel(client, {
+    workspaceAppId,
+    name: 'Booking',
+    fields: [{ shortname: 'room', name: 'Room', kind: 'string' }],
+  });
+  await createModelItem(client, {
+    input: { attributes: { modelId: model.id, fieldValuesAttributes: toFieldValuesAttributes(model, { room: 'Blu' }) } },
+  });
+  return listModelItems(client, { modelId: model.id }); // item.fieldValuesByShortname.room
+}
+
+export function Bookings() {
+  const app = useUiduApp(); // 'connecting' | 'ready' | 'error'
+  const [items, setItems] = useState<ModelItem[]>([]);
+
+  useEffect(() => {
+    if (app.status === 'ready') loadBookings(app.client, app.context.workspaceApp.id).then(setItems);
+  }, [app]);
+
+  if (app.status === 'error') return <p>Open this app from uidu ({app.error.code})</p>; // NOT_EMBEDDED, TIMEOUT…
+  return <ul>{items.map((item) => <li key={item.id}>{item.fieldValuesByShortname?.room}</li>)}</ul>;
+}
+```
+
+`app.context` carries `user`, `space`, `workspaceApp`, `locale` and `theme`. Outside React: `connect()` from
+`@uidu/app-bridge`, then `createClient(fromBridge(bridge))` from `@uidu/client`. Start a new
+one with `npm create uidu-app@latest my-app -- -t custom-app`: it declares its Models in
+`public/uidu.app.json` and sets `frame-ancestors` so only uidu can frame it.
+
 ## Working transparently
 
 The user often can't tell what you're doing when you drive the CLI. Stay legible:
@@ -280,29 +361,103 @@ const channel = await getChannel(uidu, { id: channelId });
 
 ### Forms
 
-Forms are fetched server-side, then rendered with the `useForm` hook on the client:
+Fetch the schema server-side, render it with `<DynamicForm>`, and submit through a
+**server-side** action that calls `createFormResponse`. There is no `useForm` hook.
 
 ```tsx
-// Server: fetch form schema
+// Server: fetch the form schema
 import { getForm } from '@uidu/client';
 const form = await getForm(uidu, { id: formId });
 ```
 
 ```tsx
-// Client: render with @uidu/react
+// Client: render it
 'use client';
-import { useForm } from '@uidu/react';
+import { DynamicForm } from '@uidu/react';
+import { submitForm } from '@/lib/actions';
 
 export function ContactForm({ form }) {
-  const { register, handleSubmit, onSubmit } = useForm(uidu, { form });
-  return (
-    <form onSubmit={handleSubmit(onSubmit)}>
-      {/* render fields by iterating form.formQuestions.edges */}
-    </form>
-  );
+  return <DynamicForm form={form} action={submitForm} />;
+}
+```
+
+`<DynamicForm>` renders the questions itself and hands your `action` a
+`DynamicFormValues`: `{ contact?: { firstName, lastName, email }, fieldValues:
+Array<{ fieldId, questionId, value }>, formData }`. Return `{ ok: true }` or
+`{ ok: false, errors }` and it renders the right state.
+
+#### `content` is always `{ value: … }` — never a bare value
+
+This is the one rule that breaks form writes. The API stores each answer in a JSON
+`content` column and reads it back as `content['value']`. A flat scalar is **not**
+rejected loudly: the response saves with empty typed columns, and reading that field
+later throws. `FieldValueAttributes` exposes no `value` key — `content` is the only way in.
+
+```ts
+// ✅ Correct — every answer wrapped
+fieldValuesAttributes: [{ fieldId: 'f1', content: { value: 'hello@example.com' } }]
+
+// ❌ Wrong — silently loses the answer
+fieldValuesAttributes: [{ fieldId: 'f1', content: 'hello@example.com' }]
+```
+
+It holds for **every** field kind, not just strings — `{ value: 42 }`, `{ value: true }`,
+`{ value: '2026-07-27' }`, `{ value: ['gid://…', 'gid://…'] }` for `multipleSelect`,
+`{ value: <doc> }` for `richText`/`json`. And it holds for `fieldValuesAttributes`
+**wherever** it appears — on a page block, a contact, a story, a booking — not just on
+form responses.
+
+Full submit action:
+
+```ts
+// src/lib/actions.ts
+'use server';
+import { createFormResponse } from '@uidu/client';
+import type { DynamicFormValues, DynamicFormResult } from '@uidu/react';
+import { uidu } from '@/lib/uidu';
+
+export async function submitForm(
+  values: DynamicFormValues,
+): Promise<DynamicFormResult> {
+  const result = await createFormResponse(uidu, {
+    input: {
+      event: 'complete!', // omit to save as a draft
+      attributes: {
+        formId: FORM_ID,
+        fieldValuesAttributes: values.fieldValues.map((fv) => ({
+          fieldId: fv.fieldId,
+          content: { value: fv.value }, // ← wrapped
+        })),
+        contactAttributes: values.contact && {
+          email: values.contact.email,
+          contactableAttributes: {
+            kind: 'person',
+            firstName: values.contact.firstName,
+            lastName: values.contact.lastName,
+          },
+        },
+      },
+    },
+  });
+
+  if (result?.errors?.length) return { ok: false, errors: result.errors };
+  return { ok: true, meta: { id: result?.formResponse?.id } };
 }
 ```
 
+Notes:
+
+- **Never put arbitrary keys in `attributes`.** Only what `FormResponseAttributes`
+  declares: `formId`, `fieldValuesAttributes`, `contactAttributes`, `contactId`,
+  `formPageId`, `completedAt`, `responsableId`, `id`. Unknown keys fail the mutation.
+- `event` lives on `input`, **not** inside `attributes`, and is a state-machine
+  transition (`'complete!'`, `'save_draft!'`) — not free text.
+- To record a timestamp, use `completedAt` on `attributes`, not a synthetic field value.
+- `createFormResponse` **returns** `{ errors, formResponse }` instead of throwing —
+  always check `errors` before treating a submit as successful.
+- Use `updateFormResponse` for multi-step or save-as-you-type flows; pass each
+  answer's existing `id` in `fieldValuesAttributes` to update it rather than add a new one.
+
 ## Rendering WYSIWYG Content
 
 All `body` fields on Event, Story, DonationCampaign, etc. are structured documents (not strings). Render them with `<RichText>` from `@uidu/react`:
@@ -317,7 +472,7 @@ The prop is `doc`, not `children`. The component handles paragraphs, headings, l
 
 ## Provider Setup (Client-Side Hooks)
 
-Server-side `await getX(...)` calls do not need a provider. For React client-side hooks (`useQuery`, `useFields`, `useForm`), wrap your app in `<UiduProvider>`:
+Server-side `await getX(...)` calls do not need a provider. For React client-side hooks (`useQuery`, `useUiduClient`), wrap your app in `<UiduProvider>`. (`useFields` and `toText` are pure functions — they work without a provider, on the server too.)
 
 ```tsx
 // app/layout.tsx
@@ -368,13 +523,12 @@ npm create uidu-app@latest my-app -- -t events
 | `events` | Event listing + `/event/[id]` detail |
 | `stories` | Blog listing + `/story/[id]` detail (magazine layout) |
 | `donations` | Campaigns listing + `/campaign/[id]` detail with progress bars |
+| `custom-app` | An app inside a uidu Space: `<UiduAppProvider>`, data in its own Models (`public/uidu.app.json`) |
 
-Every template ships with:
-- Next.js 16 App Router
-- Tailwind v4
-- A configured `src/lib/uidu.ts`
-- A server-rendered listing + dynamic detail page
-- `.env.example` with required vars (and the CLI offers to fill them in for you)
+Every template ships with Next.js 16 App Router, Tailwind v4 and an `.env.example` (the CLI
+offers to fill it in for you). The site templates add a configured `src/lib/uidu.ts` and a
+server-rendered listing + dynamic detail page; `custom-app` has no token to configure and
+reads everything in client components.
 
 ## See Also
 

package/skills/uidu/metadata.json

@@ -1,6 +1,6 @@
 {
   "name": "uidu",
-  "version": "0.2.0",
+  "version": "0.5.0",
   "author": "uidu",
   "license": "MIT",
   "homepage": "https://docs.uidu.org",