@sanity/workflow-studio 0.5.0 → 0.7.0

package/dist/index.cjs

@@ -1,159 +1,260 @@
 "use strict";
-Object.defineProperty(exports, "__esModule", { value: !0 });
-var workflowEngine = require("@sanity/workflow-engine"), workflowReact = require("@sanity/workflow-react"), workflowSdk = require("@sanity/workflow-sdk"), sdk = require("@sanity/sdk"), react = require("react"), sanity = require("sanity");
-function observableStore({
-  observable,
-  resolve,
-  initial
-}) {
-  let latest = initial;
-  return {
-    subscribe(onChange) {
-      const subscription = observable.subscribe((value) => {
-        latest = resolve(value), onChange();
-      });
-      return () => subscription.unsubscribe();
-    },
-    getSnapshot: () => latest
-  };
+
+Object.defineProperty(exports, "__esModule", {
+    value: !0
+});
+
+var workflowEngine = require("@sanity/workflow-engine"), observer = require("@sanity/workflow-react/observer"), observer$1 = require("@sanity/workflow-sdk/observer"), sdk = require("@sanity/sdk"), react = require("react"), sanity = require("sanity"), workflowReact = require("@sanity/workflow-react");
+
+const RESUBSCRIBE_DELAY_MS = 5e3;
+
+function observableStore({observable: observable, resolve: resolve, initial: initial, name: name}) {
+    let latest = initial;
+    return {
+        subscribe(onChange) {
+            let subscription, retry, stopped = !1;
+            const connect = () => {
+                subscription = observable.subscribe({
+                    next: value => {
+                        latest = resolve(value), onChange();
+                    },
+                    error: err => {
+                        console.error(`[workflow-studio] ${name} stream errored — resubscribing in ${RESUBSCRIBE_DELAY_MS / 1e3}s:`, err), 
+                        stopped || (retry = setTimeout(connect, RESUBSCRIBE_DELAY_MS));
+                    }
+                });
+            };
+            return connect(), () => {
+                stopped = !0, retry !== void 0 && clearTimeout(retry), subscription?.unsubscribe();
+            };
+        },
+        getSnapshot: () => latest
+    };
 }
+
 function makeStudioObserver(documentStore, options) {
-  const { mounted, engineResource, sdk: sdk2 } = options, engineIsMounted = workflowReact.sameDataset(engineResource, mounted), editStateStore = ({
-    id,
-    type,
-    release
-  }) => observableStore({
-    observable: documentStore.pair.editState(id, type, release),
-    resolve: resolveEditState,
-    initial: void 0
-  }), requireSdk = (what) => {
-    if (sdk2 !== void 0) return sdk2;
-    throw new Error(
-      `@sanity/workflow-studio: ${what} \u2014 Studio's document store is bound to ${mounted.projectId}.${mounted.dataset} and cannot observe it. Pass an App SDK instance (\`useWorkflowInstance(engine, id, {sdk})\`) to observe foreign resources.`
-    );
-  };
-  return {
-    observeInstance: (instanceId) => engineIsMounted ? editStateStore({ id: instanceId, type: workflowEngine.WORKFLOW_INSTANCE_TYPE, release: void 0 }) : workflowSdk.sdkInstanceDocStore({
-      sdk: requireSdk(
-        `instance "${instanceId}" lives in the engine dataset ${engineResource.projectId}.${engineResource.dataset}`
-      ),
-      instanceId,
-      engineResource
-    }),
-    observeDocs: (documents, perspective) => workflowReact.combineDocStores(
-      documents.map((ref) => workflowReact.classifyRef(ref, mounted) === "mounted-dataset" ? {
-        key: ref.globalDocumentId,
-        store: editStateStore({
-          id: ref.documentId,
-          type: ref.type,
-          release: workflowEngine.contentReleaseName({ ref, perspective })
-        })
-      } : {
-        key: ref.globalDocumentId,
-        store: workflowSdk.sdkContentDocStore({
-          sdk: requireSdk(`"${ref.globalDocumentId}" lives outside this workspace`),
-          ref,
-          perspective
-        })
-      })
-    ),
-    observeGuards: (instanceId, resources) => workflowReact.combineGuardStores(
-      resources.map((resource) => {
-        if (workflowReact.sameDataset(resource, mounted)) {
-          const { query, params } = workflowEngine.instanceGuardQuery(instanceId);
-          return observableStore({
-            observable: documentStore.listenQuery(query, params, {}),
-            resolve: (docs) => docs,
-            initial: workflowReact.NO_GUARDS
-          });
-        }
-        return workflowSdk.sdkGuardStore({
-          sdk: requireSdk(
-            `guards for "${instanceId}" live in ${resource.projectId}.${resource.dataset}`
-          ),
-          instanceId,
-          resource
-        });
-      })
-    )
-  };
+    const {mounted: mounted, engineResource: engineResource, sdk: sdk2, client: client} = options, engineIsMounted = observer.sameDataset(engineResource, mounted), editStateStore = ({id: id, type: type, release: release}) => observableStore({
+        observable: documentStore.pair.editState(id, type, release),
+        resolve: resolveEditState,
+        initial: void 0,
+        name: `the edit state of "${id}"`
+    }), requireSdk = what => {
+        if (sdk2 !== void 0) return sdk2;
+        throw new Error(`@sanity/workflow-studio: ${what} — Studio's document store is bound to ${mounted.projectId}.${mounted.dataset} and cannot observe it. Pass an App SDK instance via the hook's \`sdk\` option (e.g. \`useWorkflowSession({engine, instanceId, sdk})\`) to observe foreign resources.`);
+    };
+    return {
+        observeInstance: instanceId => engineIsMounted ? editStateStore({
+            id: instanceId,
+            type: workflowEngine.WORKFLOW_INSTANCE_TYPE,
+            release: void 0
+        }) : observer$1.sdkInstanceDocStore({
+            sdk: requireSdk(`instance "${instanceId}" lives in the engine dataset ${engineResource.projectId}.${engineResource.dataset}`),
+            instanceId: instanceId,
+            engineResource: engineResource
+        }),
+        observeDocs: (documents, perspective) => observer.combineDocStores(documents.map(ref => observer.classifyRef(ref, mounted) === "mounted-dataset" ? {
+            key: ref.globalDocumentId,
+            store: editStateStore({
+                id: ref.documentId,
+                type: ref.type,
+                release: workflowEngine.contentReleaseName({
+                    ref: ref,
+                    perspective: perspective
+                })
+            })
+        } : {
+            key: ref.globalDocumentId,
+            store: observer$1.sdkContentDocStore({
+                sdk: requireSdk(`"${ref.globalDocumentId}" lives outside this workspace`),
+                ref: ref,
+                perspective: perspective
+            })
+        })),
+        observeGuards: (instanceId, resources) => observer.combineGuardStores(resources.map(resource => {
+            if (observer.sameDataset(resource, mounted)) {
+                const {query: query, params: params} = workflowEngine.instanceGuardQuery(instanceId);
+                return observableStore({
+                    observable: documentStore.listenQuery(query, params, {}),
+                    resolve: docs => docs,
+                    initial: void 0,
+                    name: `the guard list for "${instanceId}"`
+                });
+            }
+            return observer$1.sdkGuardStore({
+                sdk: requireSdk(`guards for "${instanceId}" live in ${resource.projectId}.${resource.dataset}`),
+                instanceId: instanceId,
+                resource: resource
+            });
+        })),
+        observeInstances: query => engineIsMounted ? observableStore({
+            observable: documentStore.listenQuery(query.query, query.params, {}),
+            resolve: docs => docs,
+            initial: void 0,
+            name: "the instance list"
+        }) : observer$1.sdkInstancesStore({
+            sdk: requireSdk(`the instance list lives in the engine dataset ${engineResource.projectId}.${engineResource.dataset}`),
+            query: query,
+            resource: engineResource
+        }),
+        ensureDocumentExists: args => observer.ensureDocumentExists(client, args)
+    };
 }
+
 function resolveEditState(editState) {
-  if (editState.ready)
-    return editState.version ?? editState.draft ?? editState.published;
+    if (editState.ready) return editState.version ?? editState.draft ?? editState.published;
 }
-function useWorkflowInstance({
-  engine,
-  instanceId,
-  access,
-  grantsFromPath,
-  sdk: suppliedSdk
-}) {
-  const documentStore = sanity.useDocumentStore(), { projectId, dataset } = sanity.useSource(), mounted = react.useMemo(() => ({ projectId, dataset }), [projectId, dataset]), engineResource = react.useMemo(() => workflowReact.datasetResourceId(engine.workflowResource), [engine]), sdk2 = useEmbeddedSdk({
-    supplied: suppliedSdk,
-    // The engine dataset being foreign is the signal an SDK instance is
-    // needed; foreign content refs without one still fail loud per ref.
-    needed: !workflowReact.sameDataset(engineResource, mounted),
-    mounted
-  }), observer = react.useMemo(
-    () => makeStudioObserver(documentStore, {
-      mounted,
-      engineResource,
-      ...sdk2 !== void 0 ? { sdk: sdk2 } : {}
-    }),
-    [documentStore, mounted, engineResource, sdk2]
-  );
-  return workflowReact.useWorkflowSession({ engine, instanceId, observer, opts: { access, grantsFromPath } });
+
+const SESSION_CLIENT_OPTIONS = {
+    apiVersion: workflowEngine.ENGINE_API_VERSION
+};
+
+function useStudioObserver({engine: engine, sdk: suppliedSdk}) {
+    const documentStore = sanity.useDocumentStore(), source = sanity.useSource(), {projectId: projectId, dataset: dataset} = source, mounted = react.useMemo(() => ({
+        projectId: projectId,
+        dataset: dataset
+    }), [ projectId, dataset ]), engineResource = react.useMemo(() => observer.datasetResourceId(engine.workflowResource), [ engine ]), sdk2 = useEmbeddedSdk({
+        supplied: suppliedSdk,
+        needed: !observer.sameDataset(engineResource, mounted),
+        mounted: mounted,
+        sessionToken: source.getClient(SESSION_CLIENT_OPTIONS).config().token
+    });
+    return react.useMemo(() => makeStudioObserver(documentStore, {
+        mounted: mounted,
+        client: source.getClient(SESSION_CLIENT_OPTIONS),
+        engineResource: engineResource,
+        ...sdk2 !== void 0 ? {
+            sdk: sdk2
+        } : {}
+    }), [ documentStore, source, mounted, engineResource, sdk2 ]);
 }
-function useEmbeddedSdk({
-  supplied,
-  needed,
-  mounted
-}) {
-  const wanted = supplied === void 0 && needed, held = react.useRef(void 0), key = `${mounted.projectId}.${mounted.dataset}`;
-  wanted && (held.current?.key !== key || held.current.instance.isDisposed()) && (held.current = { key, instance: bootstrapInstance(mounted) });
-  const embedded = wanted ? held.current?.instance : void 0;
-  return useDeferredDispose(embedded), supplied ?? embedded;
+
+function useEmbeddedSdk({supplied: supplied, needed: needed, mounted: mounted, sessionToken: sessionToken}) {
+    const wanted = supplied === void 0 && needed, held = react.useRef(void 0), key = `${mounted.projectId}.${mounted.dataset}`;
+    wanted && (held.current?.key !== key || held.current.instance.isDisposed()) && (held.current = {
+        key: key,
+        instance: bootstrapInstance(mounted, sessionToken)
+    });
+    const embedded = wanted ? held.current?.instance : void 0;
+    return useDeferredDispose(embedded), supplied ?? embedded;
 }
-function bootstrapInstance(mounted) {
-  return sdk.createSanityInstance({
-    projectId: mounted.projectId,
-    dataset: mounted.dataset,
-    auth: { token: studioSessionToken(mounted.projectId) }
-  });
+
+function bootstrapInstance(mounted, sessionToken) {
+    if (sessionToken === void 0) throw new Error("@sanity/workflow-studio: the engine's state dataset is not this workspace's dataset, and no Studio session token is readable to bootstrap an App SDK instance (cookie-authenticated studio?). Pass one explicitly via the hook's `sdk` option, e.g. useWorkflowSession({engine, instanceId, sdk}).");
+    return sdk.createSanityInstance({
+        projectId: mounted.projectId,
+        dataset: mounted.dataset,
+        auth: {
+            token: sessionToken
+        }
+    });
 }
+
 function useDeferredDispose(instance) {
-  const disposal = react.useRef(void 0);
-  react.useEffect(() => {
-    if (instance !== void 0)
-      return disposal.current?.instance === instance && (clearTimeout(disposal.current.timeoutId), disposal.current = void 0), () => {
-        disposal.current = {
-          instance,
-          timeoutId: setTimeout(() => {
-            instance.isDisposed() || instance.dispose();
-          }, 0)
+    const disposal = react.useRef(void 0);
+    react.useEffect(() => {
+        if (instance !== void 0) return disposal.current?.instance === instance && (clearTimeout(disposal.current.timeoutId), 
+        disposal.current = void 0), () => {
+            disposal.current = {
+                instance: instance,
+                timeoutId: setTimeout(() => {
+                    instance.isDisposed() || instance.dispose();
+                }, 0)
+            };
         };
-      };
-  }, [instance]);
+    }, [ instance ]);
+}
+
+function useWorkflowEngine({workflowResource: workflowResource, tag: tag, resourceClients: resourceClients, effectHandlers: effectHandlers, missingHandler: missingHandler}) {
+    const client = sanity.useClient({
+        apiVersion: workflowEngine.ENGINE_API_VERSION
+    }), resource = observer.useKeyed([ workflowResource.type, workflowResource.id ], () => workflowResource), telemetry = workflowReact.useWorkflowTelemetry();
+    return react.useMemo(() => {
+        const engineDataset = observer.datasetResourceId(resource), engineClient = client.withConfig({
+            projectId: engineDataset.projectId,
+            dataset: engineDataset.dataset,
+            useCdn: !1,
+            requestTagPrefix: "sanity.workflows.studio"
+        });
+        return workflowEngine.createEngine({
+            client: engineClient,
+            workflowResource: resource,
+            tag: tag,
+            resourceClients: resourceClients ?? studioResourceClients(client),
+            executionContext: {
+                kind: workflowEngine.EXECUTION_KINDS.studio
+            },
+            ...effectHandlers !== void 0 ? {
+                effectHandlers: effectHandlers
+            } : {},
+            ...missingHandler !== void 0 ? {
+                missingHandler: missingHandler
+            } : {},
+            telemetry: telemetry
+        });
+    }, [ client, resource, tag, resourceClients, effectHandlers, missingHandler, telemetry ]);
+}
+
+function studioResourceClients(client) {
+    return parsed => parsed.scheme === "dataset" && parsed.projectId !== void 0 && parsed.dataset !== void 0 ? client.withConfig({
+        projectId: parsed.projectId,
+        dataset: parsed.dataset,
+        useCdn: !1,
+        requestTagPrefix: "sanity.workflows.studio"
+    }) : void 0;
+}
+
+function useWorkflowSession({engine: engine, instanceId: instanceId, grantsFromPath: grantsFromPath, sdk: sdk2}) {
+    const observer2 = useStudioObserver({
+        engine: engine,
+        sdk: sdk2
+    });
+    return workflowReact.useWorkflowSession({
+        engine: engine,
+        instanceId: instanceId,
+        observer: observer2,
+        host: "studio",
+        opts: {
+            grantsFromPath: grantsFromPath
+        }
+    });
 }
-function studioSessionToken(projectId) {
-  const token = persistedToken(projectId);
-  if (typeof token != "string")
-    throw new Error(
-      "@sanity/workflow-studio: the engine's state dataset is not this workspace's dataset, and no Studio session token is readable to bootstrap an App SDK instance (cookie-authenticated studio?). Pass one explicitly: useWorkflowInstance({engine, instanceId, sdk})."
-    );
-  return token;
+
+function useWorkflowInstances({engine: engine, filter: filter, sdk: sdk2}) {
+    const observer2 = useStudioObserver({
+        engine: engine,
+        sdk: sdk2
+    });
+    return workflowReact.useWorkflowInstances({
+        engine: engine,
+        observer: observer2,
+        ...filter !== void 0 ? {
+            filter: filter
+        } : {}
+    });
 }
-function persistedToken(projectId) {
-  const raw = window.localStorage.getItem(`__studio_auth_token_${projectId}`);
-  if (raw !== null)
-    try {
-      const parsed = JSON.parse(raw);
-      return typeof parsed != "object" || parsed === null ? void 0 : parsed.token;
-    } catch {
-      return;
-    }
+
+function useDocumentWorkflows({engine: engine, document: document, sdk: sdk2}) {
+    const observer2 = useStudioObserver({
+        engine: engine,
+        sdk: sdk2
+    });
+    return workflowReact.useDocumentWorkflows({
+        engine: engine,
+        observer: observer2,
+        document: document
+    });
 }
+
 exports.makeStudioObserver = makeStudioObserver;
-exports.useWorkflowInstance = useWorkflowInstance;
-//# sourceMappingURL=index.cjs.map
+
+exports.studioResourceClients = studioResourceClients;
+
+exports.useDocumentWorkflows = useDocumentWorkflows;
+
+exports.useStudioObserver = useStudioObserver;
+
+exports.useWorkflowEngine = useWorkflowEngine;
+
+exports.useWorkflowInstances = useWorkflowInstances;
+
+exports.useWorkflowSession = useWorkflowSession;

package/dist/index.d.cts

@@ -1,11 +1,19 @@
-import { DatasetResourceId } from "@sanity/workflow-react";
+import { DatasetResourceId } from "@sanity/workflow-react/observer";
 import type { DocumentStore } from "sanity";
-import type { Engine } from "@sanity/workflow-engine";
+import { EffectHandler } from "@sanity/workflow-engine";
+import { Engine } from "@sanity/workflow-engine";
+import type { GdrUri } from "@sanity/workflow-engine";
+import type { InstancesQueryFilter } from "@sanity/workflow-engine";
+import { MissingHandlerPolicy } from "@sanity/workflow-engine";
 import { MutationGuardDoc } from "@sanity/workflow-react";
+import { ResourceClientResolver } from "@sanity/workflow-engine";
+import type { SanityClient } from "sanity";
 import { SanityInstance } from "@sanity/sdk";
-import type { WorkflowAccessOverride } from "@sanity/workflow-engine";
-import { WorkflowInstanceController } from "@sanity/workflow-react";
-import { WorkflowObserver } from "@sanity/workflow-react";
+import { useClient } from "sanity";
+import { WorkflowInstanceList } from "@sanity/workflow-react";
+import { WorkflowObserver } from "@sanity/workflow-react/observer";
+import { WorkflowResource } from "@sanity/workflow-engine";
+import { WorkflowSession } from "@sanity/workflow-react";
 
 /**
  * A {@link WorkflowObserver} that routes every stream to the store that can
@@ -13,7 +21,8 @@ import { WorkflowObserver } from "@sanity/workflow-react";
  *
  * - Anything in the **mounted workspace dataset** → `documentStore`
  *   (`pair.editState` for docs — including Studio's local uncommitted edits,
- *   the one stream only Studio has — and `listenQuery` for guards).
+ *   the one stream only Studio has — and `listenQuery` for guards and
+ *   instance lists).
  * - Anything else (foreign content refs; the engine's state dataset when it
  *   isn't the workspace) → the App SDK store via {@link sdkInstanceDocStore} /
  *   {@link sdkContentDocStore} / {@link sdkGuardStore} when
@@ -27,10 +36,15 @@ export declare function makeStudioObserver(
 
 export { MutationGuardDoc };
 
+declare type StudioClient = ReturnType<typeof useClient>;
+
 export declare interface StudioObserverOptions {
   /** The workspace's project + dataset — the only resource Studio's
    *  `documentStore` can address. */
   mounted: DatasetResourceId;
+  /** A workspace-bound client — carries `ensureDocumentExists` writes, which
+   *  address the mounted dataset (where the workspace's subject docs live). */
+  client: SanityClient;
   /** The engine's state dataset (`datasetResourceId(engine.workflowResource)`)
    *  — where the instance doc and its verdict-relevant guards live. Routinely
    *  a dedicated `workflows` dataset distinct from the workspace. */
@@ -42,6 +56,88 @@ export declare interface StudioObserverOptions {
   sdk?: SanityInstance;
 }
 
+/**
+ * The default Studio {@link ResourceClientResolver}: any fully-addressed
+ * `dataset:` GDR resolves to the workspace client rebound to that
+ * project/dataset; other schemes (media-library, canvas) return `undefined`,
+ * letting the engine route them — a sibling client derived from the engine
+ * client's own credentials for foreign resources, its own client for the
+ * workflow resource. A custom resolver can delegate to this for the dataset
+ * arm and handle other schemes itself.
+ */
+export declare function studioResourceClients(
+  client: StudioClient,
+): ResourceClientResolver;
+
+/** Which in-flight instances reference this document (GDR URI) — live,
+ *  observed from Sanity Studio. Same routing and `sdk` rules as
+ *  {@link useWorkflowInstances}. */
+export declare function useDocumentWorkflows({
+  engine,
+  document,
+  sdk,
+}: {
+  engine: Engine;
+  document: GdrUri;
+  sdk?: SanityInstance;
+}): WorkflowInstanceList;
+
+/**
+ * The Studio observer for this engine — the shared wiring under every
+ * reactive hook in this package. Workspace-dataset streams ride
+ * `documentStore`; anything foreign (routinely the engine's dedicated
+ * `workflows` dataset) rides an App SDK instance, bootstrapped from the
+ * Studio session when the caller doesn't supply one. Must run inside Studio
+ * source context (so `useDocumentStore`/`useSource` resolve).
+ */
+export declare function useStudioObserver({
+  engine,
+  sdk: suppliedSdk,
+}: {
+  engine: Engine;
+  sdk?: SanityInstance | undefined;
+}): WorkflowObserver;
+
+/**
+ * Build the Studio-side engine once: the workspace client rebound to the
+ * engine's state dataset, plus {@link studioResourceClients} as the default
+ * per-resource routing — so subjects and refs across many content datasets
+ * resolve without call sites assembling clients. Pass `resourceClients` to
+ * override the routing (compose with {@link studioResourceClients} to keep
+ * dataset-GDR routing). `effectHandlers`/`missingHandler` feed
+ * {@link Engine.drainEffects} for engines that drain effects in the Studio.
+ * Memoized on the config's content, so inline `workflowResource` literals are
+ * fine; custom `resourceClients` and `effectHandlers` values should still be
+ * stable. Must render inside Studio source context.
+ */
+export declare function useWorkflowEngine({
+  workflowResource,
+  tag,
+  resourceClients,
+  effectHandlers,
+  missingHandler,
+}: {
+  workflowResource: WorkflowResource;
+  tag: string;
+  resourceClients?: ResourceClientResolver;
+  effectHandlers?: Record<string, EffectHandler>;
+  missingHandler?: MissingHandlerPolicy;
+}): Engine;
+
+/** A live, filterable workflow-instance list observed from Sanity Studio —
+ *  through `documentStore.listenQuery` when the engine dataset is the
+ *  workspace's own, else through an App SDK instance (auto-bootstrapped, or
+ *  supply `sdk`). Must render inside Studio source context. */
+export declare function useWorkflowInstances({
+  engine,
+  filter,
+  sdk,
+}: {
+  engine: Engine;
+  filter?: InstancesQueryFilter;
+  sdk?: SanityInstance;
+}): WorkflowInstanceList;
+
 /**
  * Drive a workflow instance reactively from Sanity Studio. Watched docs in the
  * workspace's own dataset observe through `documentStore.pair.editState`
@@ -51,24 +147,24 @@ export declare interface StudioObserverOptions {
  * from the workspace, an SDK instance is bootstrapped automatically from the
  * Studio session (pass `sdk` to supply your own — required for
  * cookie-authenticated studios, where no session token is readable). Returns
- * `{evaluation, ready, guards, tick, fireAction, editField}`; the consumer decides when
- * to advance. Must render inside Studio source context (so
- * `useDocumentStore`/`useSource` resolve).
+ * the full {@link WorkflowSession} (evaluation, ready, guards, and the
+ * tick/fireAction/editField/preview verbs); the consumer decides when to
+ * advance. Must render inside Studio source context.
  */
-export declare function useWorkflowInstance({
+export declare function useWorkflowSession({
   engine,
   instanceId,
-  access,
   grantsFromPath,
-  sdk: suppliedSdk,
+  sdk,
 }: {
   engine: Engine;
   instanceId: string;
-  access?: WorkflowAccessOverride;
   grantsFromPath?: string;
   sdk?: SanityInstance;
-}): WorkflowInstanceController;
+}): WorkflowSession;
+
+export { WorkflowInstanceList };
 
-export { WorkflowInstanceController };
+export { WorkflowSession };
 
 export {};