@salesforce/platform-sdk 12.8.0 → 12.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.
- package/dist/analytics/analytics.d.ts +19 -15
- package/dist/analytics/analytics.d.ts.map +1 -1
- package/dist/analytics/error-listener.d.ts +3 -3
- package/dist/analytics/index.d.ts.map +1 -1
- package/dist/analytics/index.js +1 -1
- package/dist/analytics/method-configs.d.ts +8 -4
- package/dist/analytics/method-configs.d.ts.map +1 -1
- package/dist/analytics/pft.d.ts +22 -16
- package/dist/analytics/pft.d.ts.map +1 -1
- package/dist/analytics/proxy.d.ts +10 -8
- package/dist/analytics/proxy.d.ts.map +1 -1
- package/dist/analytics/types.d.ts +57 -43
- package/dist/analytics/types.d.ts.map +1 -1
- package/dist/{analytics-Dpz22kda.js → analytics-wESbWdca.js} +1 -1
- package/dist/app/index.d.ts +18 -13
- package/dist/app/index.d.ts.map +1 -1
- package/dist/app/index.js +5 -3
- package/dist/app/webapp.d.ts +5 -2
- package/dist/app/webapp.d.ts.map +1 -1
- package/dist/{capabilities-CKe8z6kZ.js → capabilities-B0mU0_G0.js} +1 -1
- package/dist/chat/index.js +1 -1
- package/dist/core/app.d.ts +31 -22
- package/dist/core/app.d.ts.map +1 -1
- package/dist/core/capabilities.d.ts +26 -17
- package/dist/core/capabilities.d.ts.map +1 -1
- package/dist/core/chat.d.ts +155 -125
- package/dist/core/chat.d.ts.map +1 -1
- package/dist/core/data.d.ts +146 -107
- package/dist/core/data.d.ts.map +1 -1
- package/dist/core/extension-attach.d.ts +65 -51
- package/dist/core/extension-attach.d.ts.map +1 -1
- package/dist/core/extension-types.d.ts +214 -153
- package/dist/core/extension-types.d.ts.map +1 -1
- package/dist/core/index.d.ts.map +1 -1
- package/dist/core/index.js +2 -2
- package/dist/core/lightning.d.ts +11 -19
- package/dist/core/lightning.d.ts.map +1 -1
- package/dist/core/mcpapps-session.d.ts +63 -52
- package/dist/core/mcpapps-session.d.ts.map +1 -1
- package/dist/core/options.d.ts +6 -4
- package/dist/core/options.d.ts.map +1 -1
- package/dist/core/platforms.d.ts +29 -29
- package/dist/core/sdk-promise.d.ts +7 -4
- package/dist/core/sdk-promise.d.ts.map +1 -1
- package/dist/core/surface.d.ts +89 -67
- package/dist/core/surface.d.ts.map +1 -1
- package/dist/core/view.d.ts +164 -113
- package/dist/core/view.d.ts.map +1 -1
- package/dist/data/extensions/index.d.ts +5 -2
- package/dist/data/extensions/index.d.ts.map +1 -1
- package/dist/data/extensions/labels/index.d.ts +72 -49
- package/dist/data/extensions/labels/index.d.ts.map +1 -1
- package/dist/data/extensions/labels/query.d.ts +38 -29
- package/dist/data/extensions/labels/query.d.ts.map +1 -1
- package/dist/data/gql.d.ts +8 -4
- package/dist/data/gql.d.ts.map +1 -1
- package/dist/data/index.d.ts +67 -48
- package/dist/data/index.d.ts.map +1 -1
- package/dist/data/index.js +265 -242
- package/dist/data/mosaic/fetch.d.ts +24 -15
- package/dist/data/mosaic/fetch.d.ts.map +1 -1
- package/dist/data/mosaic/index.d.ts +13 -9
- package/dist/data/mosaic/index.d.ts.map +1 -1
- package/dist/data/openai/index.d.ts +11 -5
- package/dist/data/openai/index.d.ts.map +1 -1
- package/dist/data/shared/graphql/cache/command.d.ts +60 -46
- package/dist/data/shared/graphql/cache/command.d.ts.map +1 -1
- package/dist/data/shared/graphql/cache/invoker.d.ts.map +1 -1
- package/dist/data/shared/graphql/cache/services.d.ts +21 -11
- package/dist/data/shared/graphql/cache/services.d.ts.map +1 -1
- package/dist/data/shared/graphql/cached-graphql.d.ts +9 -4
- package/dist/data/shared/graphql/cached-graphql.d.ts.map +1 -1
- package/dist/data/shared/graphql/graphql-parse.d.ts +6 -3
- package/dist/data/shared/graphql/graphql-parse.d.ts.map +1 -1
- package/dist/data/shared/graphql/headers.d.ts +34 -27
- package/dist/data/shared/graphql/headers.d.ts.map +1 -1
- package/dist/data/shared/graphql/parse-response.d.ts +31 -23
- package/dist/data/shared/graphql/parse-response.d.ts.map +1 -1
- package/dist/data/shared/graphql/uncached-graphql.d.ts +10 -6
- package/dist/data/shared/graphql/uncached-graphql.d.ts.map +1 -1
- package/dist/data/shared/url-utils.d.ts +1 -1
- package/dist/data/shared/url-utils.d.ts.map +1 -1
- package/dist/data/webapp/accept-language.interceptor.d.ts +26 -9
- package/dist/data/webapp/accept-language.interceptor.d.ts.map +1 -1
- package/dist/data/webapp/client-headers.interceptor.d.ts +4 -3
- package/dist/data/webapp/client-headers.interceptor.d.ts.map +1 -1
- package/dist/data/webapp/csrf/header.interceptor.d.ts +4 -4
- package/dist/data/webapp/csrf/header.interceptor.d.ts.map +1 -1
- package/dist/data/webapp/csrf/retry.policy.d.ts +12 -11
- package/dist/data/webapp/csrf/retry.policy.d.ts.map +1 -1
- package/dist/data/webapp/csrf/token-manager.d.ts +18 -12
- package/dist/data/webapp/csrf/token-manager.d.ts.map +1 -1
- package/dist/data/webapp/fetch.d.ts +12 -8
- package/dist/data/webapp/fetch.d.ts.map +1 -1
- package/dist/data/webapp/index.d.ts +12 -7
- package/dist/data/webapp/index.d.ts.map +1 -1
- package/dist/i18n/locale-format.d.ts +23 -21
- package/dist/i18n/locale-format.d.ts.map +1 -1
- package/dist/i18n/salesforce-backend.d.ts +19 -11
- package/dist/i18n/salesforce-backend.d.ts.map +1 -1
- package/dist/i18n/salesforce-detector.d.ts +22 -14
- package/dist/i18n/salesforce-detector.d.ts.map +1 -1
- package/dist/index.js +3 -3
- package/dist/lightning/embedding.d.ts.map +1 -1
- package/dist/lightning/index.d.ts +4 -4
- package/dist/lightning/index.d.ts.map +1 -1
- package/dist/lightning/index.js +2 -2
- package/dist/{surface-Dd2tqrPi.js → surface-DWDgqdpN.js} +18 -13
- package/dist/telemetry/tool-adapter.d.ts.map +1 -1
- package/dist/telemetry/uploader/TelemetryUploader.d.ts.map +1 -1
- package/dist/ui-embedding/index.d.ts.map +1 -1
- package/dist/ui-embedding/session.d.ts +7 -2
- package/dist/ui-embedding/session.d.ts.map +1 -1
- package/dist/ui-embedding/session.js +1 -1
- package/dist/view/index.js +1 -1
- package/package.json +2 -2
package/dist/core/data.d.ts
CHANGED
|
@@ -5,7 +5,9 @@
|
|
|
5
5
|
*/
|
|
6
6
|
/**
|
|
7
7
|
* A single GraphQL error entry returned in a {@link GraphQLResponse}.
|
|
8
|
-
*
|
|
8
|
+
*
|
|
9
|
+
* @remarks
|
|
10
|
+
* Contains the error message and optional location and path information.
|
|
9
11
|
*/
|
|
10
12
|
export interface GraphQLError {
|
|
11
13
|
message: string;
|
|
@@ -15,18 +17,22 @@ export interface GraphQLError {
|
|
|
15
17
|
}[];
|
|
16
18
|
path?: string[];
|
|
17
19
|
/**
|
|
18
|
-
*
|
|
19
|
-
*
|
|
20
|
-
*
|
|
21
|
-
*
|
|
22
|
-
*
|
|
20
|
+
* An open, free-form error metadata map: the GraphQL `extensions` slot.
|
|
21
|
+
*
|
|
22
|
+
* @remarks
|
|
23
|
+
* This field is an unconstrained `Record`, matching the wire's own
|
|
24
|
+
* `GraphQLErrorShape`. This lets the public type mirror the
|
|
25
|
+
* pass-through behavior: a server-returned error carries whatever
|
|
26
|
+
* `extensions` the resolver attached, verbatim, with no assumed key or
|
|
27
|
+
* value shape.
|
|
23
28
|
*
|
|
24
|
-
* The one entry the SDK itself sets is `code: "CACHE_MISS"
|
|
25
|
-
* cache-control `only-if-cached` miss (see
|
|
26
|
-
*
|
|
27
|
-
*
|
|
28
|
-
*
|
|
29
|
-
*
|
|
29
|
+
* The one entry the SDK itself sets is `code: "CACHE_MISS"`. The SDK
|
|
30
|
+
* synthesizes this for a cache-control `only-if-cached` miss (see
|
|
31
|
+
* `invokeResourceGraphQL`). Callers discriminate it with
|
|
32
|
+
* `errors?.[0]?.extensions?.code === "CACHE_MISS"`. Every other
|
|
33
|
+
* SDK-synthesized failure — an invalid operation kind, a malformed
|
|
34
|
+
* query, non-serializable variables, or a network failure — sets no
|
|
35
|
+
* `code`. Callers must tell these apart by the `message` text instead.
|
|
30
36
|
*/
|
|
31
37
|
extensions?: Record<string, unknown>;
|
|
32
38
|
}
|
|
@@ -41,15 +47,20 @@ export interface GraphQLResponse<T> {
|
|
|
41
47
|
}
|
|
42
48
|
/**
|
|
43
49
|
* Extra HTTP headers to attach to a single GraphQL request, merged over the
|
|
44
|
-
* surface's canonical header set.
|
|
45
|
-
*
|
|
50
|
+
* surface's canonical header set.
|
|
51
|
+
*
|
|
52
|
+
* @remarks
|
|
53
|
+
* Caller-supplied entries take precedence. Avoid overriding transport
|
|
54
|
+
* headers such as `Content-Type` unless you intend to.
|
|
46
55
|
*
|
|
47
|
-
*
|
|
48
|
-
* `[name, value]` tuples, or a `Headers` instance
|
|
49
|
-
*
|
|
56
|
+
* This type accepts any `HeadersInit`: a plain `Record<string, string>`,
|
|
57
|
+
* an array of `[name, value]` tuples, or a `Headers` instance. You can
|
|
58
|
+
* express multi-valued headers through repeated tuples or a pre-built
|
|
59
|
+
* `Headers` object.
|
|
50
60
|
*
|
|
51
|
-
*
|
|
52
|
-
* OpenAI surface delegates to an MCP tool that
|
|
61
|
+
* Surfaces that do not issue the request over HTTP directly ignore this
|
|
62
|
+
* type. For example, the OpenAI surface delegates to an MCP tool that
|
|
63
|
+
* exposes no header channel.
|
|
53
64
|
*/
|
|
54
65
|
export type GraphQLRequestHeaders = HeadersInit;
|
|
55
66
|
/**
|
|
@@ -66,69 +77,80 @@ export interface GraphQLRequest<V = Record<string, unknown>> {
|
|
|
66
77
|
}
|
|
67
78
|
/**
|
|
68
79
|
* A GraphQL operation source string passed to {@link DataSDKGraphQL.query} or
|
|
69
|
-
* {@link DataSDKGraphQL.mutate}.
|
|
70
|
-
* Surface implementations parse the string at call time.
|
|
80
|
+
* {@link DataSDKGraphQL.mutate}.
|
|
71
81
|
*
|
|
72
|
-
*
|
|
73
|
-
*
|
|
82
|
+
* @remarks
|
|
83
|
+
* This is typically the identity output of `gql\`…\``. Surface
|
|
84
|
+
* implementations parse the string at call time.
|
|
85
|
+
*
|
|
86
|
+
* This type is aliased, rather than declared as `string`, to leave room to
|
|
87
|
+
* accept pre-parsed document nodes in a future revision without changing
|
|
88
|
+
* call sites.
|
|
74
89
|
*/
|
|
75
90
|
export type GraphQLRawDocument = string;
|
|
76
91
|
/**
|
|
77
|
-
*
|
|
92
|
+
* An unsubscribe handle returned from {@link QueryResult.subscribe}.
|
|
78
93
|
*/
|
|
79
94
|
export type Unsubscribe = () => void;
|
|
80
95
|
/**
|
|
81
|
-
*
|
|
82
|
-
*
|
|
83
|
-
*
|
|
84
|
-
*
|
|
96
|
+
* A snapshot of a query's data and errors at a single point in time.
|
|
97
|
+
*
|
|
98
|
+
* @remarks
|
|
99
|
+
* The resolved {@link QueryResult} carries this snapshot and pushes it to
|
|
100
|
+
* subscribers on every later resolution: a cache update, a
|
|
101
|
+
* stale-while-revalidate refresh, or an explicit `refresh()` call.
|
|
85
102
|
*/
|
|
86
103
|
export interface QuerySnapshot<T> {
|
|
87
104
|
data: T | undefined;
|
|
88
105
|
errors?: GraphQLError[];
|
|
89
106
|
}
|
|
90
107
|
/**
|
|
91
|
-
*
|
|
108
|
+
* A callback that runs with each new {@link QuerySnapshot}.
|
|
92
109
|
*
|
|
93
110
|
* @typeParam T - The shape of the query result data.
|
|
94
111
|
*/
|
|
95
112
|
export type QuerySubscriber<T> = (snapshot: QuerySnapshot<T>) => void;
|
|
96
113
|
/**
|
|
97
|
-
*
|
|
98
|
-
*
|
|
99
|
-
* `data` is the resolved snapshot at await-time — cached value if present
|
|
100
|
-
* (cached surfaces), otherwise the network response. `errors` carries any
|
|
101
|
-
* GraphQL or transport errors. `subscribe` streams subsequent snapshots;
|
|
102
|
-
* `refresh` re-issues the underlying request, bypassing the cache where one
|
|
103
|
-
* exists and propagating the result to subscribers.
|
|
114
|
+
* A reactive query handle resolved by {@link DataSDKGraphQL.query}.
|
|
104
115
|
*
|
|
105
116
|
* @remarks
|
|
106
|
-
*
|
|
107
|
-
*
|
|
117
|
+
* `data` is the resolved snapshot at await-time: the cached value when one
|
|
118
|
+
* is present (on cached surfaces), otherwise the network response.
|
|
119
|
+
* `errors` carries any GraphQL or transport errors. `subscribe` streams
|
|
120
|
+
* later snapshots. `refresh` re-issues the underlying request, bypasses
|
|
121
|
+
* the cache where one exists, and propagates the result to subscribers.
|
|
122
|
+
*
|
|
123
|
+
* On uncached surfaces (Mosaic, OpenAI), `subscribe` emits only in
|
|
124
|
+
* response to `refresh()`, because there is no cache to push background
|
|
125
|
+
* updates.
|
|
108
126
|
*
|
|
109
127
|
* @see docs/data/03-reactive-handle-lifecycle.md
|
|
110
128
|
*/
|
|
111
129
|
export interface QueryResult<T> extends QuerySnapshot<T> {
|
|
112
130
|
subscribe(cb: QuerySubscriber<T>): Unsubscribe;
|
|
113
131
|
/**
|
|
114
|
-
* Re-
|
|
132
|
+
* Re-fetches the query, bypassing the cache where one exists and
|
|
115
133
|
* propagating the result to subscribers.
|
|
116
134
|
*
|
|
117
135
|
* @remarks
|
|
118
|
-
*
|
|
119
|
-
* `refresh()` call
|
|
120
|
-
*
|
|
121
|
-
* populated `errors` array
|
|
122
|
-
*
|
|
123
|
-
* resulting cache state.
|
|
136
|
+
* This method never rejects. A failed re-fetch does not throw on the
|
|
137
|
+
* awaited `refresh()` call. On uncached surfaces (Mosaic, OpenAI), the
|
|
138
|
+
* method delivers the failure to `subscribe()` callbacks as a
|
|
139
|
+
* {@link QuerySnapshot} with a populated `errors` array. On cached
|
|
140
|
+
* surfaces (WebApp), a failed re-fetch is not observable on the
|
|
141
|
+
* awaited call. Subscribers receive the resulting cache state instead.
|
|
124
142
|
*/
|
|
125
143
|
refresh(): Promise<void>;
|
|
126
144
|
}
|
|
127
145
|
/**
|
|
128
|
-
*
|
|
129
|
-
*
|
|
130
|
-
*
|
|
131
|
-
*
|
|
146
|
+
* A one-shot mutation result.
|
|
147
|
+
*
|
|
148
|
+
* @remarks
|
|
149
|
+
* Mutations follow a request-and-response model: there is no `subscribe`
|
|
150
|
+
* method and no `refresh` method. Triggering a side effect again on
|
|
151
|
+
* subscription would be incoherent, and re-running a mutation on refresh
|
|
152
|
+
* would be dangerous. To handle staleness after a mutation, the caller
|
|
153
|
+
* holds query result references and calls `result.refresh()`.
|
|
132
154
|
*
|
|
133
155
|
* @see docs/data/03-reactive-handle-lifecycle.md
|
|
134
156
|
*/
|
|
@@ -137,35 +159,40 @@ export interface MutationResult<T> {
|
|
|
137
159
|
errors?: GraphQLError[];
|
|
138
160
|
}
|
|
139
161
|
/**
|
|
140
|
-
*
|
|
162
|
+
* The shorthand cache policies, passed as a plain string.
|
|
141
163
|
*
|
|
142
|
-
* - `"no-cache"` —
|
|
143
|
-
*
|
|
144
|
-
*
|
|
145
|
-
* - `"only-if-cached"` —
|
|
146
|
-
* Returns an error
|
|
164
|
+
* - `"no-cache"` — skips the cache read and fetches from the network. The
|
|
165
|
+
* surface still writes the response back to the cache for later
|
|
166
|
+
* callers. This follows the HTTP RFC 7234 `no-cache` semantics.
|
|
167
|
+
* - `"only-if-cached"` — returns the cached entry without a network call.
|
|
168
|
+
* Returns an error when no entry exists for this query and its
|
|
169
|
+
* variables.
|
|
147
170
|
*
|
|
148
171
|
* @see docs/data/02-caching-and-freshness.md
|
|
149
172
|
*/
|
|
150
173
|
export type CacheControlShorthand = "no-cache" | "only-if-cached";
|
|
151
174
|
/**
|
|
152
|
-
*
|
|
175
|
+
* Overrides the default TTL of 300 seconds with a custom max-age, in
|
|
176
|
+
* seconds.
|
|
153
177
|
*
|
|
154
178
|
* @remarks
|
|
155
|
-
* - `maxAge: 0` —
|
|
156
|
-
*
|
|
157
|
-
* -
|
|
179
|
+
* - `maxAge: 0` — the surface writes the entry but immediately treats it
|
|
180
|
+
* as stale. This always re-fetches, similar to `"no-cache"`, but it
|
|
181
|
+
* writes a 0-second TTL.
|
|
182
|
+
* - Invalid values (`NaN`, `Infinity`, or a negative number) fall back to
|
|
183
|
+
* the 300-second default.
|
|
158
184
|
*
|
|
159
185
|
* @see docs/data/02-caching-and-freshness.md
|
|
160
186
|
*/
|
|
161
187
|
export interface CacheControlMaxAge {
|
|
162
188
|
type: "max-age";
|
|
163
189
|
/**
|
|
164
|
-
*
|
|
190
|
+
* The cache TTL, in seconds.
|
|
165
191
|
*
|
|
166
192
|
* @remarks
|
|
167
|
-
*
|
|
168
|
-
* records
|
|
193
|
+
* As a rule of thumb, use a short TTL, for example about 30 seconds,
|
|
194
|
+
* for frequently-changing records. Use a longer TTL, for example about
|
|
195
|
+
* 15 minutes (900 seconds), for stable objects or metadata.
|
|
169
196
|
*
|
|
170
197
|
* @example 30
|
|
171
198
|
* @example 900
|
|
@@ -173,16 +200,18 @@ export interface CacheControlMaxAge {
|
|
|
173
200
|
maxAge: number;
|
|
174
201
|
}
|
|
175
202
|
/**
|
|
176
|
-
*
|
|
203
|
+
* The per-call cache policy for {@link DataSDKGraphQL.query}.
|
|
177
204
|
*
|
|
178
|
-
*
|
|
179
|
-
*
|
|
205
|
+
* @remarks
|
|
206
|
+
* When you omit this policy, the default `max-age` strategy with a
|
|
207
|
+
* 300-second TTL applies. After the TTL expires, the next call fetches
|
|
208
|
+
* fresh data from the network.
|
|
180
209
|
*
|
|
181
210
|
* @see docs/data/02-caching-and-freshness.md
|
|
182
211
|
*/
|
|
183
212
|
export type CacheControl = CacheControlShorthand | CacheControlMaxAge;
|
|
184
213
|
/**
|
|
185
|
-
*
|
|
214
|
+
* The options bag for {@link DataSDKGraphQL.query}.
|
|
186
215
|
*
|
|
187
216
|
* @see docs/data/02-caching-and-freshness.md
|
|
188
217
|
*/
|
|
@@ -190,25 +219,26 @@ export interface QueryOptions<V = Record<string, unknown>> {
|
|
|
190
219
|
query: GraphQLRawDocument;
|
|
191
220
|
variables?: V;
|
|
192
221
|
operationName?: string;
|
|
193
|
-
/**
|
|
222
|
+
/** Overrides the default cache behavior for this query. @see {@link CacheControl} */
|
|
194
223
|
cacheControl?: CacheControl;
|
|
195
224
|
/**
|
|
196
225
|
* Extra HTTP headers for this request, merged over the surface's canonical
|
|
197
226
|
* header set.
|
|
198
227
|
*
|
|
199
228
|
* @remarks
|
|
200
|
-
* On cached surfaces (WebApp), `headers` is part of the cache key: two
|
|
201
|
-
* that differ only in `headers` resolve to different cache
|
|
202
|
-
*
|
|
203
|
-
*
|
|
204
|
-
* equivalent headers still
|
|
229
|
+
* On cached surfaces (WebApp), `headers` is part of the cache key: two
|
|
230
|
+
* calls that differ only in `headers` resolve to different cache
|
|
231
|
+
* entries. This design stops the surface from serving a response
|
|
232
|
+
* scoped by a header, for example `Authorization`, to a later caller
|
|
233
|
+
* that passed a different value. Calls with equivalent headers still
|
|
234
|
+
* share one entry.
|
|
205
235
|
*
|
|
206
236
|
* @see {@link GraphQLRequestHeaders}
|
|
207
237
|
*/
|
|
208
238
|
headers?: GraphQLRequestHeaders;
|
|
209
239
|
}
|
|
210
240
|
/**
|
|
211
|
-
*
|
|
241
|
+
* The options bag for {@link DataSDKGraphQL.mutate}.
|
|
212
242
|
*
|
|
213
243
|
* @see docs/data/02-caching-and-freshness.md
|
|
214
244
|
*/
|
|
@@ -225,32 +255,35 @@ export interface MutateOptions<V = Record<string, unknown>> {
|
|
|
225
255
|
/**
|
|
226
256
|
* The `graphql` namespace on a {@link DataSDK}.
|
|
227
257
|
*
|
|
228
|
-
*
|
|
229
|
-
*
|
|
230
|
-
*
|
|
258
|
+
* @remarks
|
|
259
|
+
* Queries are reactive: cached on surfaces that cache, and subscribable on
|
|
260
|
+
* every surface. Mutations follow a request-and-response model. Each
|
|
261
|
+
* method's return shape matches its semantics, with no fakes and no
|
|
262
|
+
* no-ops.
|
|
231
263
|
*
|
|
232
264
|
* @see docs/data/04-surfaces-and-guards.md
|
|
233
265
|
*/
|
|
234
266
|
export interface DataSDKGraphQL {
|
|
235
267
|
/**
|
|
236
|
-
*
|
|
268
|
+
* Runs a GraphQL query.
|
|
237
269
|
*
|
|
270
|
+
* @remarks
|
|
238
271
|
* Resolves with `{ data, errors, subscribe, refresh }` once the
|
|
239
|
-
* underlying request settles
|
|
240
|
-
* only) or from the network. `subscribe` streams
|
|
241
|
-
* `refresh` re-issues the request,
|
|
242
|
-
* and
|
|
272
|
+
* underlying request settles, either from the cache (cached surfaces
|
|
273
|
+
* only) or from the network. `subscribe` streams later snapshots.
|
|
274
|
+
* `refresh` re-issues the request, bypasses the cache where one
|
|
275
|
+
* exists, and propagates the result to subscribers.
|
|
243
276
|
*
|
|
244
|
-
* On uncached surfaces (Mosaic, OpenAI), `subscribe` is real but
|
|
245
|
-
* emits in response to `refresh()
|
|
246
|
-
* updates, so `refresh()` is the sole source of new
|
|
247
|
-
* call costs one network request.
|
|
277
|
+
* On uncached surfaces (Mosaic, OpenAI), `subscribe` is real, but it
|
|
278
|
+
* emits only in response to `refresh()`. There is no cache to push
|
|
279
|
+
* background updates, so `refresh()` is the sole source of new
|
|
280
|
+
* snapshots, and each call costs one network request.
|
|
248
281
|
*
|
|
249
|
-
*
|
|
250
|
-
*
|
|
251
|
-
*
|
|
252
|
-
*
|
|
253
|
-
*
|
|
282
|
+
* The returned promise always resolves; it never rejects. This method
|
|
283
|
+
* funnels every failure — a parse error, the wrong operation kind,
|
|
284
|
+
* non-serializable variables, or a network error — into the resolved
|
|
285
|
+
* `result.errors` array. It also rejects a mutation or subscription
|
|
286
|
+
* passed here through `result.errors`.
|
|
254
287
|
*
|
|
255
288
|
* @example
|
|
256
289
|
* ```typescript
|
|
@@ -277,14 +310,17 @@ export interface DataSDKGraphQL {
|
|
|
277
310
|
*/
|
|
278
311
|
query<T, V = Record<string, unknown>>(options: QueryOptions<V>): Promise<QueryResult<T>>;
|
|
279
312
|
/**
|
|
280
|
-
*
|
|
281
|
-
* not read or write the cache. Queries and subscriptions passed here are
|
|
282
|
-
* rejected via the resolved `errors` field.
|
|
313
|
+
* Runs a GraphQL mutation.
|
|
283
314
|
*
|
|
284
315
|
* @remarks
|
|
285
|
-
*
|
|
286
|
-
*
|
|
287
|
-
*
|
|
316
|
+
* This method passes the mutation through to the underlying transport.
|
|
317
|
+
* It does not read or write the cache. It rejects a query or
|
|
318
|
+
* subscription passed here through the resolved `errors` field.
|
|
319
|
+
*
|
|
320
|
+
* The returned promise always resolves; it never rejects. This method
|
|
321
|
+
* funnels every failure — a parse error, the wrong operation kind,
|
|
322
|
+
* non-serializable variables, or a network error — into the resolved
|
|
323
|
+
* `result.errors` array.
|
|
288
324
|
*
|
|
289
325
|
* @example
|
|
290
326
|
* ```typescript
|
|
@@ -316,28 +352,31 @@ export interface DataSDKGraphQL {
|
|
|
316
352
|
/**
|
|
317
353
|
* The data SDK object returned by {@link createDataSDK}.
|
|
318
354
|
*
|
|
319
|
-
*
|
|
320
|
-
*
|
|
355
|
+
* @remarks
|
|
356
|
+
* This object may be a bare `{}` on unsupported surfaces. Feature-detect
|
|
357
|
+
* `graphql` or `fetch` before you use them, to avoid runtime errors.
|
|
321
358
|
*
|
|
322
359
|
* @see docs/data/04-surfaces-and-guards.md
|
|
323
360
|
*/
|
|
324
361
|
export interface DataSDK {
|
|
325
362
|
/**
|
|
326
|
-
* Salesforce API version
|
|
363
|
+
* The Salesforce API version that the resolved surface adapter selects.
|
|
327
364
|
*
|
|
328
|
-
*
|
|
329
|
-
*
|
|
365
|
+
* @remarks
|
|
366
|
+
* This field is present on URL-backed adapters whose request paths
|
|
367
|
+
* derive from a concrete version. Tool-backed and degraded surfaces
|
|
368
|
+
* may omit it.
|
|
330
369
|
*/
|
|
331
370
|
readonly apiVersion?: string;
|
|
332
|
-
/** GraphQL namespace. Present when the surface supports data operations. */
|
|
371
|
+
/** The GraphQL namespace. Present when the surface supports data operations. */
|
|
333
372
|
graphql?: DataSDKGraphQL;
|
|
334
373
|
/**
|
|
335
|
-
*
|
|
374
|
+
* Makes a request with the Fetch API.
|
|
336
375
|
*
|
|
337
|
-
* @param input - The URL or Request object
|
|
338
|
-
* @param init -
|
|
339
|
-
* @returns
|
|
340
|
-
* @throws {TypeError}
|
|
376
|
+
* @param input - The URL or `Request` object.
|
|
377
|
+
* @param init - The `RequestInit` configuration.
|
|
378
|
+
* @returns The response.
|
|
379
|
+
* @throws {TypeError} When the network request fails.
|
|
341
380
|
*/
|
|
342
381
|
fetch?: typeof fetch;
|
|
343
382
|
}
|
package/dist/core/data.d.ts.map
CHANGED
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"data.d.ts","sourceRoot":"","sources":["../../src/core/data.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH
|
|
1
|
+
{"version":3,"file":"data.d.ts","sourceRoot":"","sources":["../../src/core/data.ts"],"names":[],"mappings":"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"}
|
|
@@ -3,65 +3,79 @@ interface AttachExtensionsOptions<Base> {
|
|
|
3
3
|
preflight?: (entries: readonly ResolvedExtensionEntry<Base>[], base: Base) => void;
|
|
4
4
|
}
|
|
5
5
|
/**
|
|
6
|
-
*
|
|
7
|
-
* into the SDK's `ext` container
|
|
8
|
-
*
|
|
9
|
-
*
|
|
6
|
+
* Runs each extension's `setup` function in array order and mounts each
|
|
7
|
+
* returned namespace into the SDK's `ext` container.
|
|
8
|
+
*
|
|
9
|
+
* @remarks
|
|
10
|
+
* Each namespace mounts under the entry's effective mount name: its
|
|
11
|
+
* `name`, or its `as` alias when the entry is `{ extension, as }`. A
|
|
12
|
+
* `setup` function may be synchronous or asynchronous. This function
|
|
13
|
+
* awaits each one before it runs the next, so the mount order is
|
|
10
14
|
* deterministic.
|
|
11
15
|
*
|
|
12
|
-
* Compartmentalized under `ext`: every extension namespace mounts on
|
|
13
|
-
*
|
|
14
|
-
*
|
|
15
|
-
* reservation entirely
|
|
16
|
-
* surface, so it can never shadow a current or
|
|
17
|
-
* no set of names to declare off-limits. The
|
|
18
|
-
* extension
|
|
16
|
+
* Compartmentalized under `ext`: every extension namespace mounts on
|
|
17
|
+
* `sdk.ext`, for example `sdk.ext.labels`. It never mounts as a sibling of
|
|
18
|
+
* the base surface's own members, such as `graphql` or `fetch`. This
|
|
19
|
+
* design removes name reservation entirely. An extension key lives one
|
|
20
|
+
* level down from the SDK surface, so it can never shadow a current or
|
|
21
|
+
* future SDK member. There is no set of names to declare off-limits. The
|
|
22
|
+
* only collision left is one extension against another within `ext`,
|
|
23
|
+
* which still throws.
|
|
24
|
+
*
|
|
25
|
+
* Aliasing rebinds only the mount key: `setup` still runs on the
|
|
26
|
+
* underlying extension. So two extensions that both declare
|
|
27
|
+
* `name: "labels"` can attach under distinct keys, for example
|
|
28
|
+
* `{ extension: a, as: "x" }` and `{ extension: b, as: "y" }`.
|
|
19
29
|
*
|
|
20
|
-
*
|
|
21
|
-
*
|
|
22
|
-
*
|
|
30
|
+
* This function resolves the entire list before an optional `preflight`
|
|
31
|
+
* runs, and both `preflight` and `setup` consume those same resolved
|
|
32
|
+
* entries. This lets an SDK add surface-specific compatibility policy
|
|
33
|
+
* without resolving entries twice or running any `setup` before the
|
|
34
|
+
* complete list passes that policy.
|
|
23
35
|
*
|
|
24
|
-
*
|
|
25
|
-
*
|
|
26
|
-
*
|
|
27
|
-
*
|
|
36
|
+
* Each `setup` receives the base SDK, and that is all its type promises:
|
|
37
|
+
* `setup(sdk)` is typed as `Base`, never the accumulating shape. Every
|
|
38
|
+
* namespace mounts onto one shared `ext` object, attached before the loop
|
|
39
|
+
* runs. A later extension can therefore read an earlier extension's
|
|
40
|
+
* namespace at runtime, through `sdk.ext.<name>`. That reachability is an
|
|
41
|
+
* untyped byproduct, not a WI-1 contract to build on. Typed
|
|
42
|
+
* cross-extension access is WI-3. It lets an extension declare the
|
|
43
|
+
* namespaces it needs and receive them in `setup`, through the reserved
|
|
44
|
+
* `Deps` seam on {@link Extension}. Until then, author each `setup` as
|
|
45
|
+
* independent. Writing through `sdk.ext` is always blocked, during
|
|
46
|
+
* `setup` and after. See the guard below.
|
|
28
47
|
*
|
|
29
|
-
*
|
|
30
|
-
*
|
|
31
|
-
*
|
|
32
|
-
*
|
|
33
|
-
* `
|
|
34
|
-
*
|
|
35
|
-
*
|
|
36
|
-
*
|
|
37
|
-
*
|
|
38
|
-
*
|
|
48
|
+
* Atomic and non-mutating: namespaces mount onto a fresh `ext` object,
|
|
49
|
+
* hung off a fresh SDK view whose prototype is `base`. The base's own and
|
|
50
|
+
* inherited members resolve through the prototype chain, so `instanceof`
|
|
51
|
+
* still holds, while this function never writes to `base` itself. If any
|
|
52
|
+
* `setup` throws, this function simply discards the half-built view and
|
|
53
|
+
* leaves `base` pristine. There is nothing to roll back. This keeps
|
|
54
|
+
* attach safe against a memoized or shared instance, for example the chat
|
|
55
|
+
* and view singletons that WI-4 introduces. Each attach derives its own
|
|
56
|
+
* object, so a repeat attach can never collide with a prior one. The
|
|
57
|
+
* empty-extension case returns the base instance unchanged, with no
|
|
58
|
+
* `ext` key, so `ExtendedSDK<Base, []>` stays structurally `Base`.
|
|
39
59
|
*
|
|
40
|
-
*
|
|
41
|
-
*
|
|
42
|
-
*
|
|
43
|
-
*
|
|
44
|
-
*
|
|
45
|
-
* nothing to roll back. This keeps attach safe against a memoized/shared
|
|
46
|
-
* instance (e.g. the chat/view singletons WI-4 introduces): each attach derives
|
|
47
|
-
* its own object, so a repeat attach can never collide with a prior one. The
|
|
48
|
-
* empty-extension case returns the base instance unchanged — no `ext` key — so
|
|
49
|
-
* `ExtendedSDK<Base, []>` stays structurally `Base`.
|
|
60
|
+
* SDK-agnostic: this function infers `Base` from the passed instance, and
|
|
61
|
+
* it constrains `extensions` to {@link ExtensionsFor}<Base>, so only
|
|
62
|
+
* extensions compatible with this base type may attach. The returned type
|
|
63
|
+
* is {@link ExtendedSDK}<Base, Extensions> — the base plus an `ext`
|
|
64
|
+
* namespace carrying each extension's resolved API.
|
|
50
65
|
*
|
|
51
|
-
*
|
|
52
|
-
*
|
|
53
|
-
*
|
|
54
|
-
*
|
|
66
|
+
* Fail-loud: this function throws when:
|
|
67
|
+
* - the base already declares `ext`, the reserved container key
|
|
68
|
+
* - an entry is malformed — it has no `setup`, or a non-string or empty mount name
|
|
69
|
+
* - a mount name is already claimed by another extension in this call
|
|
70
|
+
* - a `setup` function throws or rejects
|
|
55
71
|
*
|
|
56
|
-
*
|
|
57
|
-
*
|
|
58
|
-
*
|
|
59
|
-
*
|
|
60
|
-
*
|
|
61
|
-
*
|
|
62
|
-
*
|
|
63
|
-
* directly throws instead of pre-claiming a mount name, and the same holds for any
|
|
64
|
-
* caller after attach returns — `ext` never becomes writable.
|
|
72
|
+
* In the extension cases, the thrown error names the extension and chains
|
|
73
|
+
* the cause. The `ext` slot is locked, so a `setup` that reassigns the
|
|
74
|
+
* container wholesale throws rather than silently dropping every
|
|
75
|
+
* namespace. `ext` itself stays immutable to everyone but this loop. A
|
|
76
|
+
* `setup` that writes `sdk.ext.<name> = …` directly throws, instead of
|
|
77
|
+
* pre-claiming a mount name. The same holds for any caller after attach
|
|
78
|
+
* returns. `ext` never becomes writable.
|
|
65
79
|
*/
|
|
66
80
|
export declare function attachExtensions<Base extends object, const Extensions extends ExtensionsFor<Base>>(base: Base, extensions: Extensions, options?: AttachExtensionsOptions<Base>): Promise<ExtendedSDK<Base, Extensions>>;
|
|
67
81
|
export {};
|
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"extension-attach.d.ts","sourceRoot":"","sources":["../../src/core/extension-attach.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AACH,OAAO,KAAK,EAEX,WAAW,EAEX,aAAa,EACb,sBAAsB,EACtB,MAAM,mBAAmB,CAAC;AAE3B,UAAU,uBAAuB,CAAC,IAAI;IACrC,SAAS,CAAC,EAAE,CAAC,OAAO,EAAE,SAAS,sBAAsB,CAAC,IAAI,CAAC,EAAE,EAAE,IAAI,EAAE,IAAI,KAAK,IAAI,CAAC;CACnF;
|
|
1
|
+
{"version":3,"file":"extension-attach.d.ts","sourceRoot":"","sources":["../../src/core/extension-attach.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AACH,OAAO,KAAK,EAEX,WAAW,EAEX,aAAa,EACb,sBAAsB,EACtB,MAAM,mBAAmB,CAAC;AAE3B,UAAU,uBAAuB,CAAC,IAAI;IACrC,SAAS,CAAC,EAAE,CAAC,OAAO,EAAE,SAAS,sBAAsB,CAAC,IAAI,CAAC,EAAE,EAAE,IAAI,EAAE,IAAI,KAAK,IAAI,CAAC;CACnF;AAoDD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA0EG;AACH,wBAAsB,gBAAgB,CACrC,IAAI,SAAS,MAAM,EACnB,KAAK,CAAC,UAAU,SAAS,aAAa,CAAC,IAAI,CAAC,EAE5C,IAAI,EAAE,IAAI,EACV,UAAU,EAAE,UAAU,EACtB,OAAO,CAAC,EAAE,uBAAuB,CAAC,IAAI,CAAC,GACrC,OAAO,CAAC,WAAW,CAAC,IAAI,EAAE,UAAU,CAAC,CAAC,CAgIxC"}
|