@sanity/workflow-studio 0.7.1 → 0.9.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (7) hide show
  1. package/CHANGELOG.md +60 -0
  2. package/README.md +57 -61
  3. package/dist/index.cjs +210 -133
  4. package/dist/index.d.cts +70 -52
  5. package/dist/index.d.ts +70 -52
  6. package/dist/index.js +212 -139
  7. package/package.json +7 -7
package/dist/index.d.cts CHANGED
@@ -1,59 +1,67 @@
1
1
  import { DatasetResourceId } from "@sanity/workflow-react/observer";
2
- import type { DocumentStore } from "sanity";
3
2
  import { EffectHandler } from "@sanity/workflow-engine";
4
3
  import { Engine } from "@sanity/workflow-engine";
4
+ import { EnsureDocumentClient } from "@sanity/workflow-react/observer";
5
5
  import type { GdrUri } from "@sanity/workflow-engine";
6
6
  import type { InstancesQueryFilter } from "@sanity/workflow-engine";
7
7
  import { MissingHandlerPolicy } from "@sanity/workflow-engine";
8
8
  import { MutationGuardDoc } from "@sanity/workflow-react";
9
+ import { ProjectUserDirectory } from "@sanity/workflow-engine";
9
10
  import { ResourceClientResolver } from "@sanity/workflow-engine";
10
- import type { SanityClient } from "sanity";
11
+ import { SanityClient } from "sanity";
11
12
  import { SanityInstance } from "@sanity/sdk";
12
- import { useClient } from "sanity";
13
+ import { User } from "sanity";
13
14
  import { WorkflowInstanceList } from "@sanity/workflow-react";
14
15
  import { WorkflowObserver } from "@sanity/workflow-react/observer";
15
16
  import { WorkflowResource } from "@sanity/workflow-engine";
16
17
  import { WorkflowSession } from "@sanity/workflow-react";
17
18
 
18
19
  /**
19
- * A {@link WorkflowObserver} that routes every stream to the store that can
20
- * actually address it:
21
- *
22
- * - Anything in the **mounted workspace dataset** → `documentStore`
23
- * (`pair.editState` for docs — including Studio's local uncommitted edits,
24
- * the one stream only Studio has — and `listenQuery` for guards and
25
- * instance lists).
26
- * - Anything else (foreign content refs; the engine's state dataset when it
27
- * isn't the workspace) → the App SDK store via {@link sdkInstanceDocStore} /
28
- * {@link sdkContentDocStore} / {@link sdkGuardStore} when
29
- * {@link StudioObserverOptions.sdk} is supplied; otherwise an actionable
30
- * error. Never a silent wrong-dataset read.
20
+ * A Studio {@link WorkflowObserver} backed entirely by the App SDK store.
21
+ * Document and query observation therefore share the SDK's resource-scoped
22
+ * live streams instead of opening one Studio listener per document or query.
23
+ * The Studio client remains the write path for ensuring workspace documents.
31
24
  */
32
25
  export declare function makeStudioObserver(
33
- documentStore: DocumentStore,
26
+ sdk: SanityInstance,
34
27
  options: StudioObserverOptions,
35
28
  ): WorkflowObserver;
36
29
 
37
30
  export { MutationGuardDoc };
38
31
 
39
- declare type StudioClient = ReturnType<typeof useClient>;
40
-
41
32
  export declare interface StudioObserverOptions {
42
- /** The workspace's project + dataset — the only resource Studio's
43
- * `documentStore` can address. */
44
- mounted: DatasetResourceId;
45
- /** A workspace-bound client — carries `ensureDocumentExists` writes, which
46
- * address the mounted dataset (where the workspace's subject docs live). */
47
- client: SanityClient;
48
- /** The engine's state dataset (`datasetResourceId(engine.workflowResource)`)
49
- * — where the instance doc and its verdict-relevant guards live. Routinely
50
- * a dedicated `workflows` dataset distinct from the workspace. */
33
+ /** A workspace-bound client for `ensureDocumentExists` writes. */
34
+ client: EnsureDocumentClient;
35
+ /** The engine's state dataset, where instance documents live. */
51
36
  engineResource: DatasetResourceId;
52
- /** Observe resources OUTSIDE the mounted dataset (foreign content refs, and
53
- * the engine dataset when it differs from the workspace) through the App
54
- * SDK store. Omit ⇒ any foreign observation throws an actionable
55
- * config-mismatch error instead of being silently misread. */
56
- sdk?: SanityInstance;
37
+ }
38
+
39
+ export declare interface StudioProjectMembership {
40
+ readonly id: string;
41
+ readonly isRobot?: boolean;
42
+ readonly roles?: readonly {
43
+ readonly name: string;
44
+ }[];
45
+ readonly [key: string]: unknown;
46
+ }
47
+
48
+ /** Unprojected upstream records for one Studio project user. */
49
+ export declare interface StudioProjectUser {
50
+ readonly membership: StudioProjectMembership;
51
+ readonly profile: StudioUserProfile | undefined;
52
+ }
53
+
54
+ /** Studio integration shared by actor lookup and the project-member picker. */
55
+ export declare function studioProjectUserDirectory(
56
+ client: StudioUserClient,
57
+ projectId: string,
58
+ ): ProjectUserDirectory<StudioProjectUser>;
59
+
60
+ export declare interface StudioProjectUsersState {
61
+ readonly users: readonly StudioProjectUser[];
62
+ readonly loading: boolean;
63
+ readonly error: unknown;
64
+ readonly directory: ProjectUserDirectory<StudioProjectUser> | undefined;
57
65
  }
58
66
 
59
67
  /**
@@ -66,9 +74,22 @@ export declare interface StudioObserverOptions {
66
74
  * arm and handle other schemes itself.
67
75
  */
68
76
  export declare function studioResourceClients(
69
- client: StudioClient,
77
+ client: SanityClient,
70
78
  ): ResourceClientResolver;
71
79
 
80
+ declare interface StudioUserClient {
81
+ readonly config: () => {
82
+ readonly projectId?: string;
83
+ };
84
+ readonly request: (options: { readonly uri: string }) => Promise<unknown>;
85
+ }
86
+
87
+ /** Native Studio profile response, whose nullable avatar is wider than Sanity's public type. */
88
+ export declare interface StudioUserProfile extends Omit<User, "imageUrl"> {
89
+ readonly imageUrl?: string | null;
90
+ readonly [key: string]: unknown;
91
+ }
92
+
72
93
  /** Which in-flight instances reference this document (GDR URI) — live,
73
94
  * observed from Sanity Studio. Same routing and `sdk` rules as
74
95
  * {@link useWorkflowInstances}. */
@@ -84,11 +105,10 @@ export declare function useDocumentWorkflows({
84
105
 
85
106
  /**
86
107
  * The Studio observer for this engine — the shared wiring under every
87
- * reactive hook in this package. Workspace-dataset streams ride
88
- * `documentStore`; anything foreign (routinely the engine's dedicated
89
- * `workflows` dataset) rides an App SDK instance, bootstrapped from the
90
- * Studio session when the caller doesn't supply one. Must run inside Studio
91
- * source context (so `useDocumentStore`/`useSource` resolve).
108
+ * reactive hook in this package. Every stream rides an App SDK instance,
109
+ * bootstrapped from the Studio session when the caller doesn't supply one.
110
+ * Must run inside Studio source context so `useSource` can resolve the
111
+ * workspace client and SDK configuration.
92
112
  */
93
113
  export declare function useStudioObserver({
94
114
  engine,
@@ -98,6 +118,8 @@ export declare function useStudioObserver({
98
118
  sdk?: SanityInstance | undefined;
99
119
  }): WorkflowObserver;
100
120
 
121
+ export declare function useStudioProjectUsers(): StudioProjectUsersState;
122
+
101
123
  /**
102
124
  * Build the Studio-side engine once: the workspace client rebound to the
103
125
  * engine's state dataset, plus {@link studioResourceClients} as the default
@@ -120,14 +142,13 @@ export declare function useWorkflowEngine({
120
142
  workflowResource: WorkflowResource;
121
143
  tag: string;
122
144
  resourceClients?: ResourceClientResolver;
123
- effectHandlers?: Record<string, EffectHandler>;
145
+ effectHandlers?: Record<string, EffectHandler<SanityClient>>;
124
146
  missingHandler?: MissingHandlerPolicy;
125
147
  }): Engine;
126
148
 
127
- /** A live, filterable workflow-instance list observed from Sanity Studio —
128
- * through `documentStore.listenQuery` when the engine dataset is the
129
- * workspace's own, else through an App SDK instance (auto-bootstrapped, or
130
- * supply `sdk`). Must render inside Studio source context. */
149
+ /** A live, filterable workflow-instance list observed from Sanity Studio
150
+ * through an App SDK instance (auto-bootstrapped, or supply `sdk`). Must
151
+ * render inside Studio source context. */
131
152
  export declare function useWorkflowInstances({
132
153
  engine,
133
154
  filter,
@@ -139,15 +160,12 @@ export declare function useWorkflowInstances({
139
160
  }): WorkflowInstanceList;
140
161
 
141
162
  /**
142
- * Drive a workflow instance reactively from Sanity Studio. Watched docs in the
143
- * workspace's own dataset observe through `documentStore.pair.editState`
144
- * (including local uncommitted edits); everything else — the engine's state
145
- * dataset (routinely a dedicated `workflows` dataset) and foreign content
146
- * refs — observes through the App SDK store. When the engine dataset differs
147
- * from the workspace, an SDK instance is bootstrapped automatically from the
148
- * Studio session (pass `sdk` to supply your own — required for
149
- * cookie-authenticated studios, where no session token is readable). Returns
150
- * the full {@link WorkflowSession} (evaluation, ready, guards, and the
163
+ * Drive a workflow instance reactively from Sanity Studio. Every document and
164
+ * query observes through the App SDK store, including the mounted workspace
165
+ * and the engine's state dataset. An SDK instance is bootstrapped automatically
166
+ * in Studio mode, following Studio's token or cookie authentication reactively
167
+ * (pass `sdk` to supply your own). Returns the full {@link WorkflowSession}
168
+ * (evaluation, ready, guards, and the
151
169
  * tick/fireAction/editField/preview verbs); the consumer decides when to
152
170
  * advance. Must render inside Studio source context.
153
171
  */
package/dist/index.d.ts CHANGED
@@ -1,59 +1,67 @@
1
1
  import { DatasetResourceId } from "@sanity/workflow-react/observer";
2
- import type { DocumentStore } from "sanity";
3
2
  import { EffectHandler } from "@sanity/workflow-engine";
4
3
  import { Engine } from "@sanity/workflow-engine";
4
+ import { EnsureDocumentClient } from "@sanity/workflow-react/observer";
5
5
  import type { GdrUri } from "@sanity/workflow-engine";
6
6
  import type { InstancesQueryFilter } from "@sanity/workflow-engine";
7
7
  import { MissingHandlerPolicy } from "@sanity/workflow-engine";
8
8
  import { MutationGuardDoc } from "@sanity/workflow-react";
9
+ import { ProjectUserDirectory } from "@sanity/workflow-engine";
9
10
  import { ResourceClientResolver } from "@sanity/workflow-engine";
10
- import type { SanityClient } from "sanity";
11
+ import { SanityClient } from "sanity";
11
12
  import { SanityInstance } from "@sanity/sdk";
12
- import { useClient } from "sanity";
13
+ import { User } from "sanity";
13
14
  import { WorkflowInstanceList } from "@sanity/workflow-react";
14
15
  import { WorkflowObserver } from "@sanity/workflow-react/observer";
15
16
  import { WorkflowResource } from "@sanity/workflow-engine";
16
17
  import { WorkflowSession } from "@sanity/workflow-react";
17
18
 
18
19
  /**
19
- * A {@link WorkflowObserver} that routes every stream to the store that can
20
- * actually address it:
21
- *
22
- * - Anything in the **mounted workspace dataset** → `documentStore`
23
- * (`pair.editState` for docs — including Studio's local uncommitted edits,
24
- * the one stream only Studio has — and `listenQuery` for guards and
25
- * instance lists).
26
- * - Anything else (foreign content refs; the engine's state dataset when it
27
- * isn't the workspace) → the App SDK store via {@link sdkInstanceDocStore} /
28
- * {@link sdkContentDocStore} / {@link sdkGuardStore} when
29
- * {@link StudioObserverOptions.sdk} is supplied; otherwise an actionable
30
- * error. Never a silent wrong-dataset read.
20
+ * A Studio {@link WorkflowObserver} backed entirely by the App SDK store.
21
+ * Document and query observation therefore share the SDK's resource-scoped
22
+ * live streams instead of opening one Studio listener per document or query.
23
+ * The Studio client remains the write path for ensuring workspace documents.
31
24
  */
32
25
  export declare function makeStudioObserver(
33
- documentStore: DocumentStore,
26
+ sdk: SanityInstance,
34
27
  options: StudioObserverOptions,
35
28
  ): WorkflowObserver;
36
29
 
37
30
  export { MutationGuardDoc };
38
31
 
39
- declare type StudioClient = ReturnType<typeof useClient>;
40
-
41
32
  export declare interface StudioObserverOptions {
42
- /** The workspace's project + dataset — the only resource Studio's
43
- * `documentStore` can address. */
44
- mounted: DatasetResourceId;
45
- /** A workspace-bound client — carries `ensureDocumentExists` writes, which
46
- * address the mounted dataset (where the workspace's subject docs live). */
47
- client: SanityClient;
48
- /** The engine's state dataset (`datasetResourceId(engine.workflowResource)`)
49
- * — where the instance doc and its verdict-relevant guards live. Routinely
50
- * a dedicated `workflows` dataset distinct from the workspace. */
33
+ /** A workspace-bound client for `ensureDocumentExists` writes. */
34
+ client: EnsureDocumentClient;
35
+ /** The engine's state dataset, where instance documents live. */
51
36
  engineResource: DatasetResourceId;
52
- /** Observe resources OUTSIDE the mounted dataset (foreign content refs, and
53
- * the engine dataset when it differs from the workspace) through the App
54
- * SDK store. Omit ⇒ any foreign observation throws an actionable
55
- * config-mismatch error instead of being silently misread. */
56
- sdk?: SanityInstance;
37
+ }
38
+
39
+ export declare interface StudioProjectMembership {
40
+ readonly id: string;
41
+ readonly isRobot?: boolean;
42
+ readonly roles?: readonly {
43
+ readonly name: string;
44
+ }[];
45
+ readonly [key: string]: unknown;
46
+ }
47
+
48
+ /** Unprojected upstream records for one Studio project user. */
49
+ export declare interface StudioProjectUser {
50
+ readonly membership: StudioProjectMembership;
51
+ readonly profile: StudioUserProfile | undefined;
52
+ }
53
+
54
+ /** Studio integration shared by actor lookup and the project-member picker. */
55
+ export declare function studioProjectUserDirectory(
56
+ client: StudioUserClient,
57
+ projectId: string,
58
+ ): ProjectUserDirectory<StudioProjectUser>;
59
+
60
+ export declare interface StudioProjectUsersState {
61
+ readonly users: readonly StudioProjectUser[];
62
+ readonly loading: boolean;
63
+ readonly error: unknown;
64
+ readonly directory: ProjectUserDirectory<StudioProjectUser> | undefined;
57
65
  }
58
66
 
59
67
  /**
@@ -66,9 +74,22 @@ export declare interface StudioObserverOptions {
66
74
  * arm and handle other schemes itself.
67
75
  */
68
76
  export declare function studioResourceClients(
69
- client: StudioClient,
77
+ client: SanityClient,
70
78
  ): ResourceClientResolver;
71
79
 
80
+ declare interface StudioUserClient {
81
+ readonly config: () => {
82
+ readonly projectId?: string;
83
+ };
84
+ readonly request: (options: { readonly uri: string }) => Promise<unknown>;
85
+ }
86
+
87
+ /** Native Studio profile response, whose nullable avatar is wider than Sanity's public type. */
88
+ export declare interface StudioUserProfile extends Omit<User, "imageUrl"> {
89
+ readonly imageUrl?: string | null;
90
+ readonly [key: string]: unknown;
91
+ }
92
+
72
93
  /** Which in-flight instances reference this document (GDR URI) — live,
73
94
  * observed from Sanity Studio. Same routing and `sdk` rules as
74
95
  * {@link useWorkflowInstances}. */
@@ -84,11 +105,10 @@ export declare function useDocumentWorkflows({
84
105
 
85
106
  /**
86
107
  * The Studio observer for this engine — the shared wiring under every
87
- * reactive hook in this package. Workspace-dataset streams ride
88
- * `documentStore`; anything foreign (routinely the engine's dedicated
89
- * `workflows` dataset) rides an App SDK instance, bootstrapped from the
90
- * Studio session when the caller doesn't supply one. Must run inside Studio
91
- * source context (so `useDocumentStore`/`useSource` resolve).
108
+ * reactive hook in this package. Every stream rides an App SDK instance,
109
+ * bootstrapped from the Studio session when the caller doesn't supply one.
110
+ * Must run inside Studio source context so `useSource` can resolve the
111
+ * workspace client and SDK configuration.
92
112
  */
93
113
  export declare function useStudioObserver({
94
114
  engine,
@@ -98,6 +118,8 @@ export declare function useStudioObserver({
98
118
  sdk?: SanityInstance | undefined;
99
119
  }): WorkflowObserver;
100
120
 
121
+ export declare function useStudioProjectUsers(): StudioProjectUsersState;
122
+
101
123
  /**
102
124
  * Build the Studio-side engine once: the workspace client rebound to the
103
125
  * engine's state dataset, plus {@link studioResourceClients} as the default
@@ -120,14 +142,13 @@ export declare function useWorkflowEngine({
120
142
  workflowResource: WorkflowResource;
121
143
  tag: string;
122
144
  resourceClients?: ResourceClientResolver;
123
- effectHandlers?: Record<string, EffectHandler>;
145
+ effectHandlers?: Record<string, EffectHandler<SanityClient>>;
124
146
  missingHandler?: MissingHandlerPolicy;
125
147
  }): Engine;
126
148
 
127
- /** A live, filterable workflow-instance list observed from Sanity Studio —
128
- * through `documentStore.listenQuery` when the engine dataset is the
129
- * workspace's own, else through an App SDK instance (auto-bootstrapped, or
130
- * supply `sdk`). Must render inside Studio source context. */
149
+ /** A live, filterable workflow-instance list observed from Sanity Studio
150
+ * through an App SDK instance (auto-bootstrapped, or supply `sdk`). Must
151
+ * render inside Studio source context. */
131
152
  export declare function useWorkflowInstances({
132
153
  engine,
133
154
  filter,
@@ -139,15 +160,12 @@ export declare function useWorkflowInstances({
139
160
  }): WorkflowInstanceList;
140
161
 
141
162
  /**
142
- * Drive a workflow instance reactively from Sanity Studio. Watched docs in the
143
- * workspace's own dataset observe through `documentStore.pair.editState`
144
- * (including local uncommitted edits); everything else — the engine's state
145
- * dataset (routinely a dedicated `workflows` dataset) and foreign content
146
- * refs — observes through the App SDK store. When the engine dataset differs
147
- * from the workspace, an SDK instance is bootstrapped automatically from the
148
- * Studio session (pass `sdk` to supply your own — required for
149
- * cookie-authenticated studios, where no session token is readable). Returns
150
- * the full {@link WorkflowSession} (evaluation, ready, guards, and the
163
+ * Drive a workflow instance reactively from Sanity Studio. Every document and
164
+ * query observes through the App SDK store, including the mounted workspace
165
+ * and the engine's state dataset. An SDK instance is bootstrapped automatically
166
+ * in Studio mode, following Studio's token or cookie authentication reactively
167
+ * (pass `sdk` to supply your own). Returns the full {@link WorkflowSession}
168
+ * (evaluation, ready, guards, and the
151
169
  * tick/fireAction/editField/preview verbs); the consumer decides when to
152
170
  * advance. Must render inside Studio source context.
153
171
  */