@collective-intelligence/extensions-sdk-frontend-react 0.1.8 → 0.1.9

package/README.md

@@ -140,6 +140,80 @@ The chart exposes every declared input and output with its port name, direction,
 connection limit, and allowed peer constraints. Port targets are 20 pixels wide;
 the card grows to keep dense port lists and contextual add controls separated.
 
+## Studio API
+
+The `studio-api` entrypoint is a generated client for the backend operations
+that hosted Studio Widgets are meant to use. The backend marks each such
+operation with the `widget-public` OpenAPI tag. The tag selects what the client
+generates; it is not an authorization boundary. Each request runs with the
+signed-in user's own permissions, and the backend authorizes it like any other
+request. The entrypoint exports the SDK functions, their types, TanStack Query
+options, mutation options and query keys, and the `client` instance. The Studio
+Host binds that client to its authenticated transport; Widgets do not configure
+credentials. Every Widget shares the one bound `client`, so the Host locks it:
+`client.setConfig` and every `client.interceptors` change throw. Set headers
+and other request options per call.
+
+### Studio view context
+
+The Studio Host gives every placed view and Widget component a `context` prop
+next to its configured props. The `/studio` entrypoint types it as
+`StudioViewComponentProps`:
+
+```ts
+type StudioViewContext = Readonly<{
+  appId: string
+  appSlug: string
+  organizationId: string
+  pageId: string
+  publishedRevisionId: string
+  viewId: string
+}>
+type StudioViewComponentProps = Readonly<{
+  context: StudioViewContext | null
+}>
+```
+
+Studio generates view, page, and revision ids when an app is installed or
+published, so a declaration cannot name them; read them from `context`.
+`context` is `null` when the view has no published placement: in the builder
+preview, without an Organization, or before the app has a published revision.
+Hide or disable the API calls of the Widget in that case.
+
+`studioViewScope(context)` returns the `headers` and `path` options of the
+view-data operations. `studioPublishedViewScope(context)` returns the
+`headers` and `query` options of operations on a published view, such as
+`studioWorkflowRunsList`:
+
+```tsx
+import type {
+  StudioViewComponentProps,
+  StudioViewContext
+} from "@collective-intelligence/extensions-sdk-frontend-react/studio"
+
+import { studioViewScope } from "@collective-intelligence/extensions-sdk-frontend-react/studio"
+import { studioViewDataSearchOptions } from "@collective-intelligence/extensions-sdk-frontend-react/studio-api"
+import { useQuery } from "@tanstack/react-query"
+
+const CustomerRows = ({ context }: { context: StudioViewContext }) => {
+  const rows = useQuery(
+    studioViewDataSearchOptions({
+      ...studioViewScope(context),
+      body: { limit: 10 }
+    })
+  )
+  return <output>{rows.status}</output>
+}
+
+export const CustomerWidget = ({ context }: StudioViewComponentProps) =>
+  context === null ? null : <CustomerRows context={context} />
+```
+
+`src/studio-api/` is generated and committed. After a backend change to a
+marked operation, run `bun run --filter @repo/backend api:openapi`, then
+`bun run api:codegen:studio-api` in this package. CI runs
+`api:codegen:studio-api:check` and fails when the committed client is stale.
+
 ## Building in the workspace
 
 This package needs the built `@collective-intelligence/ui-react` declarations

package/dist/index.d.ts

@@ -1,5 +1,19 @@
-import { declareStudioApp as declareStudioAppImplementation, declareStudioComponent as declareStudioComponentImplementation } from "./studio-declarations.js";
-export declare const declareStudioApp: typeof declareStudioAppImplementation;
+import { declareStudioComponent as declareStudioComponentImplementation } from "./studio-declarations.js";
+export declare const declareStudioApp: (input: import("@collective-intelligence/extensions-sdk").StudioAppDeclarationInput) => import("@collective-intelligence/extensions-sdk").DeclaredComponent<import("@collective-intelligence/extensions-sdk").StudioAppDeclaration>;
+export declare const declareStudioAppTemplate: (input: Readonly<{
+    definition: Omit<import("@collective-intelligence/extensions-sdk").StudioAppTemplateDeclaration, "description" | "displayName" | "fqn" | "icon" | "kind" | "tags" | "version">;
+    manifest: Readonly<{
+        fqn: string;
+        version: string;
+    }>;
+    presentation: Readonly<{
+        description?: string;
+        displayName: string;
+        icon?: string;
+        tags?: readonly string[];
+    }>;
+}>) => import("@collective-intelligence/extensions-sdk").DeclaredComponent<import("@collective-intelligence/extensions-sdk").StudioAppTemplateDeclaration>;
 export declare const declareStudioComponent: typeof declareStudioComponentImplementation;
-export type { LocalizedStudioText, StudioAppDeclaration, StudioAppDeclarationInput, StudioAppDefinition, StudioAppPageDefinition, StudioAppSectionDefinition, StudioComponentComposition, StudioComponentDeclaration, StudioComponentDeclarationInput } from "./studio-declarations.js";
+export type { StudioAppDeclaration, StudioAppDeclarationInput, StudioAppDefinition, StudioAppPageDefinition, StudioAppSectionDefinition, StudioAppTemplateDeclaration, StudioAppTemplateDefinition, StudioAppTemplatePageDefinition, StudioAppTemplateSectionDefinition } from "@collective-intelligence/extensions-sdk";
+export type { LocalizedStudioText, StudioComponentComposition, StudioComponentDeclaration, StudioComponentDeclarationInput } from "./studio-declarations.js";
 export type { HostedContributionErrorBoundaryProps, HostedContributionLoadFailure, HostedContributionLoadState, HostedContributionUnavailableProps } from "./load-state.js";

package/dist/index.js

@@ -1 +1 @@
-import{assertConsumerProfile as s,canonicalJson as d,normalizePackageSchemaProjection as c}from"@collective-intelligence/extensions-sdk";var a=(o)=>{try{d(o)}catch(e){let t=e instanceof Error?e.message:String(e);throw TypeError(`Studio declaration must be serializable JSON: ${t}`,{cause:e})}},r=(o)=>{let e={...o.definition,...o.presentation,...o.manifest,kind:"studioApp"};return a(e),{manifest:e,schemaSidecars:[]}},p=(o)=>{let e=o.definition.propsSchema,t=`studio_component:${o.manifest.fqn}.propsSchema`,n=c(e.project("input"));s(n,"studio_props",t);let i={category:o.definition.category,...o.definition.composition===void 0?void 0:{composition:o.definition.composition},...o.presentation,...o.manifest,kind:"studioComponent",propsSchema:n,sourceRef:o.definition.sourceRef};return a(i),{manifest:i,schemaSidecars:[{direction:"input",location:t,profile:"studio_props",source:e}]}};var f=r,g=p;export{f as declareStudioApp,g as declareStudioComponent};
+import{declareStudioApp as d,declareStudioAppTemplate as m}from"@collective-intelligence/extensions-sdk";import{assertConsumerProfile as r,canonicalJson as p,normalizePackageSchemaProjection as c}from"@collective-intelligence/extensions-sdk";var s=(o)=>{try{p(o)}catch(e){let t=e instanceof Error?e.message:String(e);throw TypeError(`Studio declaration must be serializable JSON: ${t}`,{cause:e})}},a=(o)=>{let e=o.definition.propsSchema,t=`studio_component:${o.manifest.fqn}.propsSchema`,n=c(e.project("input"));r(n,"studio_props",t);let i={category:o.definition.category,...o.definition.composition===void 0?void 0:{composition:o.definition.composition},...o.presentation,...o.manifest,kind:"studioComponent",propsSchema:n,sourceRef:o.definition.sourceRef};return s(i),{manifest:i,schemaSidecars:[{direction:"input",location:t,profile:"studio_props",source:e}]}};var g=d,y=m,D=a;export{g as declareStudioApp,y as declareStudioAppTemplate,D as declareStudioComponent};