@collective-intelligence/extensions-sdk-frontend-react 0.1.31 → 0.1.32

package/README.md

@@ -8,8 +8,8 @@ React and React DOM are host-provided peers. The optional
 `/workflow` or `/ui-react` subpaths; declaration-only consumers do not need it.
 
 `effect` (`^4.1.0`) is a required peer: the app installs one copy of `effect`,
-and the package build keeps it external. The `/effect` entrypoint is reserved
-for the Effect API of this package and exports nothing in this release.
+and the package build keeps it external. The `/effect` entrypoint exports the
+`StudioApi` service; see [Studio API on Effect](#studio-api-on-effect).
 
 ```tsx
 import { declareFrontendCatalogContribution } from "@collective-intelligence/extensions-sdk-frontend"
@@ -217,6 +217,70 @@ export const CustomerWidget = ({ context }: StudioViewComponentProps) =>
 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.
+A new operation also needs its method in `StudioApi`; a test fails until it
+has one.
+
+### Studio API on Effect
+
+The `/effect` entrypoint exports the `StudioApi` service. It has one method per
+operation of the `studio-api` client, with the same name, request options and
+success type. `StudioApi` calls the shared `studio-api` client: it imports the
+client through `./studio-api`, so a Studio Widget calls the client that the
+Studio Host binds. A Studio Extension release bundles `/effect` and keeps
+`/studio-api` external; the release build needs a `ci` CLI version that
+bundles an SDK `./effect` subpath (see the CLI changelog). Only the Studio
+Host provides `/studio-api`. A Dashboard release bundles its own copy of the
+client, and no Host binds that copy.
+
+`/effect` imports each operation of `/studio-api` by name. In a Studio
+Extension, the Studio Host provides that module. If the `/studio-api` of the
+Host does not export one of these operations, `/effect` does not load, also
+for a Widget that does not call that operation. Use `/effect` only with a
+Studio Host that ships this SDK version or a later one that keeps each
+operation.
+
+```ts
+import type { StudioViewContext } from "@collective-intelligence/extensions-sdk-frontend-react/studio"
+
+import {
+  layerStudioApi,
+  StudioApi
+} from "@collective-intelligence/extensions-sdk-frontend-react/effect"
+import { studioPublishedViewScope } from "@collective-intelligence/extensions-sdk-frontend-react/studio"
+import * as Effect from "effect/Effect"
+
+const runCount = (context: StudioViewContext) =>
+  Effect.gen(function* () {
+    const api = yield* StudioApi
+    const page = yield* api.studioWorkflowRunsList(
+      studioPublishedViewScope(context)
+    )
+    return page.data.length
+  }).pipe(
+    Effect.catchTag("StudioApiError", (error) => Effect.fail(error.status)),
+    Effect.provide(layerStudioApi())
+  )
+```
+
+- An error answer fails with `StudioApiError`. It holds the `status` and the
+  `body` that the client read (JSON, else text). The client does not check
+  `body`, and a status outside the generated error map, such as a 502 of a
+  proxy, holds any body. So `body` is `unknown`: decode it with a Schema
+  before use.
+- A request that does not reach the Backend, or an OK answer that is not
+  readable, fails with `StudioApiTransportError`, which holds the `cause`.
+- Bad input, such as a body that JSON cannot write, is a `TypeError` Defect.
+  The request does not leave.
+- An interruption of the fiber aborts the request.
+- The service sets `client`, `fetch`, `baseUrl`, `signal`, `responseStyle` and
+  `throwOnError`. Set headers and the other request options per call.
+
+`layerStudioApi({ baseUrl })` sends each request to `baseUrl`. A Studio Widget
+gives no base URL: the Host binds the client to its Backend and refuses other
+URLs. A host that does not bind the client, such as a test or a preview, gives
+the URL of its Backend. That URL is deployment configuration, so
+`layerStudioApiConfig({ baseUrl: Config.String("STUDIO_API_BASE_URL") })`
+reads it with Effect `Config`.
 
 ## Building in the workspace
 

package/dist/effect/studio-api/service.d.ts

@@ -0,0 +1,112 @@
+/**
+ * The Studio API on the Effect Core: one method per operation of the
+ * generated `./studio-api` client. The service imports that client through
+ * the package's own `./studio-api` subpath, which the Studio Host provides
+ * and binds to its Backend transport, so a Studio Extension calls the client
+ * that the Host binds.
+ *
+ * An error answer fails with `StudioApiError`. A request that does not reach
+ * the Backend, or an OK answer that is not readable, fails with
+ * `StudioApiTransportError`.
+ */
+import type { Options, StudioAgentRunsGetData, StudioAgentRunsGetErrors, StudioAgentRunsGetResponses, StudioAgentRunsListData, StudioAgentRunsListErrors, StudioAgentRunsListResponses, StudioViewDataGetItemData, StudioViewDataGetItemErrors, StudioViewDataGetItemResponses, StudioViewDataSearchData, StudioViewDataSearchErrors, StudioViewDataSearchMembersData, StudioViewDataSearchMembersErrors, StudioViewDataSearchMembersResponses, StudioViewDataSearchResponses, StudioViewDataUpdateItemData, StudioViewDataUpdateItemErrors, StudioViewDataUpdateItemResponses, StudioWorkflowRunsGetData, StudioWorkflowRunsGetErrors, StudioWorkflowRunsGetResponses, StudioWorkflowRunsListData, StudioWorkflowRunsListErrors, StudioWorkflowRunsListResponses } from "@collective-intelligence/extensions-sdk-frontend-react/studio-api";
+import * as Config from "effect/Config";
+import * as Context from "effect/Context";
+import * as Effect from "effect/Effect";
+import * as Layer from "effect/Layer";
+import { StudioApiError, StudioApiTransportError } from "../../errors";
+/** The request data, success map and error map of each generated operation. */
+type Generated = Readonly<{
+    studioAgentRunsGet: [
+        StudioAgentRunsGetData,
+        StudioAgentRunsGetResponses,
+        StudioAgentRunsGetErrors
+    ];
+    studioAgentRunsList: [
+        StudioAgentRunsListData,
+        StudioAgentRunsListResponses,
+        StudioAgentRunsListErrors
+    ];
+    studioViewDataGetItem: [
+        StudioViewDataGetItemData,
+        StudioViewDataGetItemResponses,
+        StudioViewDataGetItemErrors
+    ];
+    studioViewDataSearch: [
+        StudioViewDataSearchData,
+        StudioViewDataSearchResponses,
+        StudioViewDataSearchErrors
+    ];
+    studioViewDataSearchMembers: [
+        StudioViewDataSearchMembersData,
+        StudioViewDataSearchMembersResponses,
+        StudioViewDataSearchMembersErrors
+    ];
+    studioViewDataUpdateItem: [
+        StudioViewDataUpdateItemData,
+        StudioViewDataUpdateItemResponses,
+        StudioViewDataUpdateItemErrors
+    ];
+    studioWorkflowRunsGet: [
+        StudioWorkflowRunsGetData,
+        StudioWorkflowRunsGetResponses,
+        StudioWorkflowRunsGetErrors
+    ];
+    studioWorkflowRunsList: [
+        StudioWorkflowRunsListData,
+        StudioWorkflowRunsListResponses,
+        StudioWorkflowRunsListErrors
+    ];
+}>;
+/** The name of one generated operation. */
+export type StudioApiOperationName = keyof Generated;
+/** The options that the service sets on each call of the generated client. */
+type CallOptions = Readonly<{
+    baseUrl?: string;
+    fetch: typeof globalThis.fetch;
+    responseStyle: "fields";
+    signal: AbortSignal;
+    throwOnError: false;
+}>;
+/**
+ * The request options of one operation, less those that the service sets;
+ * the service always calls the shared client.
+ */
+export type StudioApiRequest<Name extends StudioApiOperationName> = Omit<Options<Generated[Name][0], false>, keyof CallOptions | "client">;
+/** The one value type of a generated status map, such as `{ 200: Page }`. */
+type ValueOf<Map> = Map[keyof Map];
+/** The success value of one operation: the generated success type. */
+export type StudioApiSuccess<Name extends StudioApiOperationName> = ValueOf<Generated[Name][1]>;
+/** One operation of `StudioApi`. */
+export type StudioApiOperation<Name extends StudioApiOperationName> = (request: StudioApiRequest<Name>) => Effect.Effect<StudioApiSuccess<Name>, StudioApiError | StudioApiTransportError>;
+export type StudioApiValue = Readonly<{
+    [Name in StudioApiOperationName]: StudioApiOperation<Name>;
+}>;
+declare const StudioApi_base: Context.ServiceClass<StudioApi, "@collective-intelligence/extensions-sdk-frontend-react/StudioApi", Readonly<{
+    studioAgentRunsGet: StudioApiOperation<"studioAgentRunsGet">;
+    studioAgentRunsList: StudioApiOperation<"studioAgentRunsList">;
+    studioViewDataGetItem: StudioApiOperation<"studioViewDataGetItem">;
+    studioViewDataSearch: StudioApiOperation<"studioViewDataSearch">;
+    studioViewDataSearchMembers: StudioApiOperation<"studioViewDataSearchMembers">;
+    studioViewDataUpdateItem: StudioApiOperation<"studioViewDataUpdateItem">;
+    studioWorkflowRunsGet: StudioApiOperation<"studioWorkflowRunsGet">;
+    studioWorkflowRunsList: StudioApiOperation<"studioWorkflowRunsList">;
+}>>;
+export declare class StudioApi extends StudioApi_base {
+}
+export type StudioApiOptions = Readonly<{
+    /**
+     * The base URL of each request. A Studio Extension leaves it out: the
+     * Studio Host binds the client to its Backend.
+     */
+    baseUrl?: string;
+}>;
+export declare const make: (options?: StudioApiOptions) => StudioApiValue;
+/** `StudioApi` over the `./studio-api` client. */
+export declare const layer: (options?: StudioApiOptions) => Layer.Layer<StudioApi, never, never>;
+/**
+ * `layer` with options that Effect `Config` reads: the base URL is
+ * deployment configuration of a host that does not bind the client.
+ */
+export declare const layerConfig: (config: Config.Wrap<StudioApiOptions>) => Layer.Layer<StudioApi, Config.ConfigError, never>;
+export {};

package/dist/effect.d.ts

@@ -1 +1,3 @@
-export {};
+export { StudioApiError, StudioApiTransportError } from "./errors.js";
+export { StudioApi, layer as layerStudioApi, layerConfig as layerStudioApiConfig } from "./effect/studio-api/service.js";
+export type { StudioApiOperation, StudioApiOperationName, StudioApiOptions, StudioApiRequest, StudioApiSuccess, StudioApiValue } from "./effect/studio-api/service.js";

package/dist/effect.js

@@ -0,0 +1 @@
+import*as o from"effect/Schema";class d extends o.TaggedError()("StudioApiError",{body:o.Unknown,status:o.Int}){}class n extends o.TaggedError()("StudioApiTransportError",{cause:o.Defect()}){}import{client as g,studioAgentRunsGet as y,studioAgentRunsList as h,studioViewDataGetItem as E,studioViewDataSearch as G,studioViewDataSearchMembers as k,studioViewDataUpdateItem as O,studioWorkflowRunsGet as x,studioWorkflowRunsList as L}from"@collective-intelligence/extensions-sdk-frontend-react/studio-api";import*as f from"effect/Config";import*as c from"effect/Context";import*as u from"effect/Effect";import*as p from"effect/Layer";class S extends c.Service()("@collective-intelligence/extensions-sdk-frontend-react/StudioApi"){}var N=(s={})=>{let w=s.baseUrl===void 0?{}:{baseUrl:s.baseUrl},i=(t,e)=>u.fn(`StudioApi.${t}`)(function*(A){let l=!1,m=g.getConfig().fetch??globalThis.fetch,D=Object.assign(async(r,V)=>(l=!0,await m(r,V)),m),a=yield*u.tryPromise({catch:(r)=>{if(l)return new n({cause:r});throw r},try:(r)=>e(A,{...w,fetch:D,responseStyle:"fields",signal:r,throwOnError:!1})});if(a.response===void 0)return yield*new n({cause:a.error});if(!a.response.ok)return yield*new d({body:a.error,status:a.response.status});return a.data});return S.of({studioAgentRunsGet:i("studioAgentRunsGet",(t,e)=>y({...t,...e})),studioAgentRunsList:i("studioAgentRunsList",(t,e)=>h({...t,...e})),studioViewDataGetItem:i("studioViewDataGetItem",(t,e)=>E({...t,...e})),studioViewDataSearch:i("studioViewDataSearch",(t,e)=>G({...t,...e})),studioViewDataSearchMembers:i("studioViewDataSearchMembers",(t,e)=>k({...t,...e})),studioViewDataUpdateItem:i("studioViewDataUpdateItem",(t,e)=>O({...t,...e})),studioWorkflowRunsGet:i("studioWorkflowRunsGet",(t,e)=>x({...t,...e})),studioWorkflowRunsList:i("studioWorkflowRunsList",(t,e)=>L({...t,...e}))})},R=(s={})=>p.sync(S,()=>N(s)),b=(s)=>p.unwrap(u.map(f.unwrap(s),R));export{S as StudioApi,d as StudioApiError,n as StudioApiTransportError,R as layerStudioApi,b as layerStudioApiConfig};

package/dist/errors.d.ts

@@ -0,0 +1,20 @@
+import * as Schema from "effect/Schema";
+declare const StudioApiError_base: Schema.Class<StudioApiError, Schema.TaggedStruct<"StudioApiError", {
+    /**
+     * The error answer as the generated client reads it: JSON, else text.
+     * The client does not check it, and a status outside the generated error
+     * map, such as a 502 of a proxy, holds any body: decode it before use.
+     */
+    readonly body: Schema.Unknown;
+    readonly status: Schema.Int;
+}>, import("effect/Cause").YieldableError>;
+/** A Studio API operation got an answer with an error status. */
+export declare class StudioApiError extends StudioApiError_base {
+}
+declare const StudioApiTransportError_base: Schema.Class<StudioApiTransportError, Schema.TaggedStruct<"StudioApiTransportError", {
+    readonly cause: Schema.Defect;
+}>, import("effect/Cause").YieldableError>;
+/** The request did not reach the Backend, or its OK answer is not readable. */
+export declare class StudioApiTransportError extends StudioApiTransportError_base {
+}
+export {};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@collective-intelligence/extensions-sdk-frontend-react",
-  "version": "0.1.31",
+  "version": "0.1.32",
   "description": "Public hosted React contribution contracts for Collective Intelligence extensions.",
   "type": "module",
   "sideEffects": false,
@@ -64,20 +64,21 @@
     "api:codegen:studio-api": "bun tools/codegen/generate-studio-api.ts",
     "api:codegen:studio-api:check": "bun tools/codegen/generate-studio-api.ts --check",
     "build": "bun tools/build.ts",
-    "test": "bun test src tools && bun run test:pack && vitest run test/frontend-runtime.test.tsx test/built-runtime.test.ts test/workflow-field-help.test.tsx",
-    "test:unit": "bun test src",
+    "test": "bun --conditions=ci-source test src tools && bun run test:pack && vitest run test/frontend-runtime.test.tsx test/built-runtime.test.ts test/workflow-field-help.test.tsx",
+    "test:unit": "bun --conditions=ci-source test src",
     "test:pack": "bun tools/test-pack.ts",
+    "test:properties": "vitest run test/properties",
     "format": "oxfmt --write .",
     "format:check": "oxfmt --check .",
     "format:check:staged": "oxfmt --check",
     "lint": "node \"../../../.agents/scripts/managed-lint-runner.mjs\" --scope \"packages/public/extensions-sdk-frontend-react\"",
     "lint:staged": "oxlint --no-error-on-unmatched-pattern",
     "prepack": "bun run build",
-    "type-check": "bun check"
+    "type-check": "bun check && bun check -p tsconfig.type-tests.json"
   },
   "dependencies": {
-    "@collective-intelligence/extensions-sdk": "0.1.30",
-    "@collective-intelligence/extensions-sdk-frontend": "0.1.30"
+    "@collective-intelligence/extensions-sdk": "0.1.31",
+    "@collective-intelligence/extensions-sdk-frontend": "0.1.31"
   },
   "peerDependencies": {
     "@collective-intelligence/ui-react": "0.1.26",
@@ -97,6 +98,7 @@
   },
   "devDependencies": {
     "@collective-intelligence/ui-react": "0.1.26",
+    "@effect/vitest": "4.1.0",
     "@hey-api/openapi-ts": "^0.96.0",
     "@oxlint/plugins": "1.90.0",
     "@tanstack/react-query": "5.101.4",
@@ -114,8 +116,8 @@
     "react-dom": "^19.2.8",
     "typescript": "7.0.2",
     "ultracite": "7.10.7",
-    "vitest": "^3.2.7",
+    "vitest": "5.0.2",
     "es-module-lexer": "2.3.2"
   },
-  "gitHead": "24d1d077eeb604df774f04db008630b8c10d130c"
+  "gitHead": "b46c00d8ce76db49b810e7a3f25933ace4f2252f"
 }