@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.
Files changed (116) hide show
  1. package/dist/analytics/analytics.d.ts +19 -15
  2. package/dist/analytics/analytics.d.ts.map +1 -1
  3. package/dist/analytics/error-listener.d.ts +3 -3
  4. package/dist/analytics/index.d.ts.map +1 -1
  5. package/dist/analytics/index.js +1 -1
  6. package/dist/analytics/method-configs.d.ts +8 -4
  7. package/dist/analytics/method-configs.d.ts.map +1 -1
  8. package/dist/analytics/pft.d.ts +22 -16
  9. package/dist/analytics/pft.d.ts.map +1 -1
  10. package/dist/analytics/proxy.d.ts +10 -8
  11. package/dist/analytics/proxy.d.ts.map +1 -1
  12. package/dist/analytics/types.d.ts +57 -43
  13. package/dist/analytics/types.d.ts.map +1 -1
  14. package/dist/{analytics-Dpz22kda.js → analytics-wESbWdca.js} +1 -1
  15. package/dist/app/index.d.ts +18 -13
  16. package/dist/app/index.d.ts.map +1 -1
  17. package/dist/app/index.js +5 -3
  18. package/dist/app/webapp.d.ts +5 -2
  19. package/dist/app/webapp.d.ts.map +1 -1
  20. package/dist/{capabilities-CKe8z6kZ.js → capabilities-B0mU0_G0.js} +1 -1
  21. package/dist/chat/index.js +1 -1
  22. package/dist/core/app.d.ts +31 -22
  23. package/dist/core/app.d.ts.map +1 -1
  24. package/dist/core/capabilities.d.ts +26 -17
  25. package/dist/core/capabilities.d.ts.map +1 -1
  26. package/dist/core/chat.d.ts +155 -125
  27. package/dist/core/chat.d.ts.map +1 -1
  28. package/dist/core/data.d.ts +146 -107
  29. package/dist/core/data.d.ts.map +1 -1
  30. package/dist/core/extension-attach.d.ts +65 -51
  31. package/dist/core/extension-attach.d.ts.map +1 -1
  32. package/dist/core/extension-types.d.ts +214 -153
  33. package/dist/core/extension-types.d.ts.map +1 -1
  34. package/dist/core/index.d.ts.map +1 -1
  35. package/dist/core/index.js +2 -2
  36. package/dist/core/lightning.d.ts +11 -19
  37. package/dist/core/lightning.d.ts.map +1 -1
  38. package/dist/core/mcpapps-session.d.ts +63 -52
  39. package/dist/core/mcpapps-session.d.ts.map +1 -1
  40. package/dist/core/options.d.ts +6 -4
  41. package/dist/core/options.d.ts.map +1 -1
  42. package/dist/core/platforms.d.ts +29 -29
  43. package/dist/core/sdk-promise.d.ts +7 -4
  44. package/dist/core/sdk-promise.d.ts.map +1 -1
  45. package/dist/core/surface.d.ts +89 -67
  46. package/dist/core/surface.d.ts.map +1 -1
  47. package/dist/core/view.d.ts +164 -113
  48. package/dist/core/view.d.ts.map +1 -1
  49. package/dist/data/extensions/index.d.ts +5 -2
  50. package/dist/data/extensions/index.d.ts.map +1 -1
  51. package/dist/data/extensions/labels/index.d.ts +72 -49
  52. package/dist/data/extensions/labels/index.d.ts.map +1 -1
  53. package/dist/data/extensions/labels/query.d.ts +38 -29
  54. package/dist/data/extensions/labels/query.d.ts.map +1 -1
  55. package/dist/data/gql.d.ts +8 -4
  56. package/dist/data/gql.d.ts.map +1 -1
  57. package/dist/data/index.d.ts +67 -48
  58. package/dist/data/index.d.ts.map +1 -1
  59. package/dist/data/index.js +265 -242
  60. package/dist/data/mosaic/fetch.d.ts +24 -15
  61. package/dist/data/mosaic/fetch.d.ts.map +1 -1
  62. package/dist/data/mosaic/index.d.ts +13 -9
  63. package/dist/data/mosaic/index.d.ts.map +1 -1
  64. package/dist/data/openai/index.d.ts +11 -5
  65. package/dist/data/openai/index.d.ts.map +1 -1
  66. package/dist/data/shared/graphql/cache/command.d.ts +60 -46
  67. package/dist/data/shared/graphql/cache/command.d.ts.map +1 -1
  68. package/dist/data/shared/graphql/cache/invoker.d.ts.map +1 -1
  69. package/dist/data/shared/graphql/cache/services.d.ts +21 -11
  70. package/dist/data/shared/graphql/cache/services.d.ts.map +1 -1
  71. package/dist/data/shared/graphql/cached-graphql.d.ts +9 -4
  72. package/dist/data/shared/graphql/cached-graphql.d.ts.map +1 -1
  73. package/dist/data/shared/graphql/graphql-parse.d.ts +6 -3
  74. package/dist/data/shared/graphql/graphql-parse.d.ts.map +1 -1
  75. package/dist/data/shared/graphql/headers.d.ts +34 -27
  76. package/dist/data/shared/graphql/headers.d.ts.map +1 -1
  77. package/dist/data/shared/graphql/parse-response.d.ts +31 -23
  78. package/dist/data/shared/graphql/parse-response.d.ts.map +1 -1
  79. package/dist/data/shared/graphql/uncached-graphql.d.ts +10 -6
  80. package/dist/data/shared/graphql/uncached-graphql.d.ts.map +1 -1
  81. package/dist/data/shared/url-utils.d.ts +1 -1
  82. package/dist/data/shared/url-utils.d.ts.map +1 -1
  83. package/dist/data/webapp/accept-language.interceptor.d.ts +26 -9
  84. package/dist/data/webapp/accept-language.interceptor.d.ts.map +1 -1
  85. package/dist/data/webapp/client-headers.interceptor.d.ts +4 -3
  86. package/dist/data/webapp/client-headers.interceptor.d.ts.map +1 -1
  87. package/dist/data/webapp/csrf/header.interceptor.d.ts +4 -4
  88. package/dist/data/webapp/csrf/header.interceptor.d.ts.map +1 -1
  89. package/dist/data/webapp/csrf/retry.policy.d.ts +12 -11
  90. package/dist/data/webapp/csrf/retry.policy.d.ts.map +1 -1
  91. package/dist/data/webapp/csrf/token-manager.d.ts +18 -12
  92. package/dist/data/webapp/csrf/token-manager.d.ts.map +1 -1
  93. package/dist/data/webapp/fetch.d.ts +12 -8
  94. package/dist/data/webapp/fetch.d.ts.map +1 -1
  95. package/dist/data/webapp/index.d.ts +12 -7
  96. package/dist/data/webapp/index.d.ts.map +1 -1
  97. package/dist/i18n/locale-format.d.ts +23 -21
  98. package/dist/i18n/locale-format.d.ts.map +1 -1
  99. package/dist/i18n/salesforce-backend.d.ts +19 -11
  100. package/dist/i18n/salesforce-backend.d.ts.map +1 -1
  101. package/dist/i18n/salesforce-detector.d.ts +22 -14
  102. package/dist/i18n/salesforce-detector.d.ts.map +1 -1
  103. package/dist/index.js +3 -3
  104. package/dist/lightning/embedding.d.ts.map +1 -1
  105. package/dist/lightning/index.d.ts +4 -4
  106. package/dist/lightning/index.d.ts.map +1 -1
  107. package/dist/lightning/index.js +2 -2
  108. package/dist/{surface-Dd2tqrPi.js → surface-DWDgqdpN.js} +18 -13
  109. package/dist/telemetry/tool-adapter.d.ts.map +1 -1
  110. package/dist/telemetry/uploader/TelemetryUploader.d.ts.map +1 -1
  111. package/dist/ui-embedding/index.d.ts.map +1 -1
  112. package/dist/ui-embedding/session.d.ts +7 -2
  113. package/dist/ui-embedding/session.d.ts.map +1 -1
  114. package/dist/ui-embedding/session.js +1 -1
  115. package/dist/view/index.js +1 -1
  116. package/package.json +2 -2
@@ -1,29 +1,38 @@
1
1
  import { FetchService, RequestInterceptor } from '@conduit-client/service-fetch-network/v1';
2
2
  /**
3
- * Decides whether a request should pivot to the lightning domain: only when the
4
- * widget is trusted (`isInternal`), a `lightningDomain` is configured, and
5
- * the request carries the first-party header. When true, `lightningDomain` is
6
- * narrowed to `string` at the call site.
3
+ * Returns `true` when a request must pivot to the lightning domain.
4
+ *
5
+ * @remarks
6
+ * A request pivots only when the widget is trusted (`isInternal`), a
7
+ * `lightningDomain` is configured, and the request carries the first-party
8
+ * header. When the result is `true`, the call site narrows `lightningDomain`
9
+ * to `string`.
7
10
  */
8
11
  export declare function shouldPivotToLightning(init: RequestInit | undefined, isInternal: boolean, lightningDomain: string | undefined): lightningDomain is string;
9
- /** Configuration for the Mosaic fetch transport. */
12
+ /** The configuration for the Mosaic fetch transport. */
10
13
  interface MosaicFetchConfig {
11
- /** My-domain base URL for resolving relative paths (e.g., "https://myorg.salesforce.com"). */
14
+ /**
15
+ * The my-domain base URL for resolving relative paths, for example
16
+ * "https://myorg.salesforce.com".
17
+ */
12
18
  baseUrl?: string;
13
- /** Access token; sent as a bearer header, or as the sid cookie on a lightning pivot. */
19
+ /** The access token, sent as a Bearer header or as the sid cookie on a lightning pivot. */
14
20
  accessToken?: string;
15
- /** Lightning-domain base URL for UITier (first-party) requests. */
21
+ /** The lightning-domain base URL for UITier (first-party) requests. */
16
22
  lightningDomain?: string;
17
- /** Whether this widget is trusted to pivot first-party requests to the lightning domain. */
23
+ /** True when this widget is trusted to pivot first-party requests to the lightning domain. */
18
24
  isInternal?: boolean;
19
25
  }
20
26
  /**
21
- * The single request interceptor for the Mosaic transport. Routing and auth are
22
- * resolved together so they cannot diverge: a first-party request from a trusted
23
- * widget is routed to the lightning domain with sid-cookie auth; everything else
24
- * goes to my-domain with bearer auth. The pivot only fires for a relative URL
25
- * being rewritten against `baseUrl`, so the sid cookie can never attach unless
26
- * the request is actually bound for the lightning domain.
27
+ * The single request interceptor for the Mosaic transport.
28
+ *
29
+ * @remarks
30
+ * The interceptor resolves routing and authentication together, so they cannot
31
+ * diverge: it routes a first-party request from a trusted widget to the lightning
32
+ * domain with sid-cookie authentication, and sends everything else to my-domain
33
+ * with Bearer authentication. The pivot fires only for a relative URL that the
34
+ * interceptor rewrites against `baseUrl`, so the sid cookie can never attach
35
+ * unless the request is bound for the lightning domain.
27
36
  */
28
37
  export declare function createMosaicInterceptor({ baseUrl, accessToken, lightningDomain, isInternal, }: MosaicFetchConfig): RequestInterceptor;
29
38
  /** Creates a fetch service configured with the Mosaic request interceptor. */
@@ -1 +1 @@
1
- {"version":3,"file":"fetch.d.ts","sourceRoot":"","sources":["../../../src/data/mosaic/fetch.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,EAIN,KAAK,YAAY,EACjB,KAAK,kBAAkB,EACvB,MAAM,0CAA0C,CAAC;AAelD;;;;;GAKG;AACH,wBAAgB,sBAAsB,CACrC,IAAI,EAAE,WAAW,GAAG,SAAS,EAC7B,UAAU,EAAE,OAAO,EACnB,eAAe,EAAE,MAAM,GAAG,SAAS,GACjC,eAAe,IAAI,MAAM,CAG3B;AAcD,oDAAoD;AACpD,UAAU,iBAAiB;IAC1B,8FAA8F;IAC9F,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,wFAAwF;IACxF,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,mEAAmE;IACnE,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,4FAA4F;IAC5F,UAAU,CAAC,EAAE,OAAO,CAAC;CACrB;AAED;;;;;;;GAOG;AACH,wBAAgB,uBAAuB,CAAC,EACvC,OAAO,EACP,WAAW,EACX,eAAe,EACf,UAAkB,GAClB,EAAE,iBAAiB,GAAG,kBAAkB,CAkBxC;AAED,8EAA8E;AAC9E,wBAAgB,wBAAwB,CAAC,MAAM,EAAE,iBAAiB,GAAG,YAAY,CAKhF"}
1
+ {"version":3,"file":"fetch.d.ts","sourceRoot":"","sources":["../../../src/data/mosaic/fetch.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,EAIN,KAAK,YAAY,EACjB,KAAK,kBAAkB,EACvB,MAAM,0CAA0C,CAAC;AAelD;;;;;;;;GAQG;AACH,wBAAgB,sBAAsB,CACrC,IAAI,EAAE,WAAW,GAAG,SAAS,EAC7B,UAAU,EAAE,OAAO,EACnB,eAAe,EAAE,MAAM,GAAG,SAAS,GACjC,eAAe,IAAI,MAAM,CAG3B;AAiBD,wDAAwD;AACxD,UAAU,iBAAiB;IAC1B;;;OAGG;IACH,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,2FAA2F;IAC3F,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,uEAAuE;IACvE,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,8FAA8F;IAC9F,UAAU,CAAC,EAAE,OAAO,CAAC;CACrB;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,uBAAuB,CAAC,EACvC,OAAO,EACP,WAAW,EACX,eAAe,EACf,UAAkB,GAClB,EAAE,iBAAiB,GAAG,kBAAkB,CAmBxC;AAED,8EAA8E;AAC9E,wBAAgB,wBAAwB,CAAC,MAAM,EAAE,iBAAiB,GAAG,YAAY,CAKhF"}
@@ -1,8 +1,10 @@
1
1
  import { DataSDK, DataSDKGraphQL } from '../../core';
2
2
  /**
3
- * Options for the Mosaic surface — the server-side (Node.js) surface. Auth is
4
- * via access token and there is no cache. Passed as `DataSDKOptions.mosaic`.
3
+ * The options for the Mosaic surface, the server-side (Node.js) surface.
5
4
  *
5
+ * @remarks
6
+ * This surface authenticates with an access token and has no cache. Callers
7
+ * pass these options as `DataSDKOptions.mosaic`.
6
8
  * @see docs/data/04-surfaces-and-guards.md
7
9
  */
8
10
  export interface MosaicDataSDKOptions {
@@ -22,22 +24,24 @@ export interface MosaicDataSDKOptions {
22
24
  */
23
25
  apiVersion?: string;
24
26
  /**
25
- * The lightning domain base URL used for UITier (first-party) requests
26
- * when the widget is trusted as internal.
27
+ * The lightning-domain base URL for UITier (first-party) requests when this
28
+ * widget is trusted as internal.
27
29
  * @example "https://my-domain.lightning.force.com"
28
30
  */
29
31
  lightningDomain?: string;
30
32
  /**
31
- * Marks this widget as internal/trusted, enabling the lightning-domain
32
- * pivot for first-party (UITier) requests. Defaults to false.
33
+ * Marks this widget as internal and trusted, which enables the
34
+ * lightning-domain pivot for first-party (UITier) requests. Defaults to `false`.
33
35
  */
34
36
  isInternal?: boolean;
35
37
  }
36
38
  /**
37
- * Data SDK implementation for the Mosaic surface (Node.js / server-side).
39
+ * The data SDK implementation for the Mosaic surface (Node.js, server-side).
38
40
  *
39
- * Uses the conduit-client fetch service without CSRF protection or session handling.
40
- * Authentication is handled via an access token provided through options or MOSAIC_ENV.
41
+ * @remarks
42
+ * This class uses the conduit-client fetch service without CSRF protection
43
+ * or session handling. It authenticates with an access token from the
44
+ * options or from `MOSAIC_ENV`.
41
45
  */
42
46
  export declare class MosaicDataSDK implements DataSDK {
43
47
  private readonly clientFetch;
@@ -1 +1 @@
1
- {"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/data/mosaic/index.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAIH,OAAO,KAAK,EAAE,OAAO,EAAE,cAAc,EAAmC,MAAM,YAAY,CAAC;AAe3F;;;;;GAKG;AACH,MAAM,WAAW,oBAAoB;IACpC;;;OAGG;IACH,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB;;;OAGG;IACH,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB;;;OAGG;IACH,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB;;;;OAIG;IACH,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB;;;OAGG;IACH,UAAU,CAAC,EAAE,OAAO,CAAC;CACrB;AAED;;;;;GAKG;AACH,qBAAa,aAAc,YAAW,OAAO;IAC5C,OAAO,CAAC,QAAQ,CAAC,WAAW,CAAe;IAC3C,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAS;IAClC,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAqB;IAC7C,OAAO,CAAC,QAAQ,CAAC,eAAe,CAAqB;IACrD,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAU;IACrC,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,OAAO,EAAE,cAAc,CAAC;gBAErB,OAAO,CAAC,EAAE,oBAAoB;YA0B5B,iBAAiB;CA4D/B"}
1
+ {"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/data/mosaic/index.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAIH,OAAO,KAAK,EAAE,OAAO,EAAE,cAAc,EAAmC,MAAM,YAAY,CAAC;AAkB3F;;;;;;;GAOG;AACH,MAAM,WAAW,oBAAoB;IACpC;;;OAGG;IACH,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB;;;OAGG;IACH,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB;;;OAGG;IACH,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB;;;;OAIG;IACH,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB;;;OAGG;IACH,UAAU,CAAC,EAAE,OAAO,CAAC;CACrB;AAED;;;;;;;GAOG;AACH,qBAAa,aAAc,YAAW,OAAO;IAC5C,OAAO,CAAC,QAAQ,CAAC,WAAW,CAAe;IAC3C,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAS;IAClC,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAqB;IAC7C,OAAO,CAAC,QAAQ,CAAC,eAAe,CAAqB;IACrD,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAU;IACrC,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,OAAO,EAAE,cAAc,CAAC;gBAErB,OAAO,CAAC,EAAE,oBAAoB;YA0B5B,iBAAiB;CA4D/B"}
@@ -1,15 +1,21 @@
1
1
  import { DataSDK, DataSDKGraphQL } from '../../core';
2
2
  /**
3
- * Data SDK implementation for the OpenAI surface, which delegates GraphQL
4
- * queries to the Salesforce MCP server via the ChatGPT bridge.
3
+ * The data SDK implementation for the OpenAI surface.
4
+ *
5
+ * @remarks
6
+ * This class delegates GraphQL queries to the Salesforce MCP server through
7
+ * the ChatGPT bridge.
5
8
  */
6
9
  export declare class OpenAIDataSDK implements DataSDK {
7
10
  readonly graphql: DataSDKGraphQL;
8
11
  constructor();
9
12
  /**
10
- * The `headers` request option is intentionally not forwarded: this surface
11
- * delegates to the `graphqlQuery` MCP tool over the ChatGPT bridge, which
12
- * issues the HTTP request host-side and exposes no header channel.
13
+ * This method does not forward the `headers` request option, by design.
14
+ *
15
+ * @remarks
16
+ * This surface delegates to the `graphqlQuery` MCP tool through the
17
+ * ChatGPT bridge. The bridge issues the HTTP request on the host side and
18
+ * exposes no header channel.
13
19
  */
14
20
  private executeRawGraphQL;
15
21
  }
@@ -1 +1 @@
1
- {"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/data/openai/index.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AACH,OAAO,KAAK,EAAE,OAAO,EAAE,cAAc,EAAmC,MAAM,YAAY,CAAC;AAK3F;;;GAGG;AACH,qBAAa,aAAc,YAAW,OAAO;IAC5C,QAAQ,CAAC,OAAO,EAAE,cAAc,CAAC;;IAMjC;;;;OAIG;YACW,iBAAiB;CAa/B"}
1
+ {"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/data/openai/index.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AACH,OAAO,KAAK,EAAE,OAAO,EAAE,cAAc,EAAmC,MAAM,YAAY,CAAC;AAK3F;;;;;;GAMG;AACH,qBAAa,aAAc,YAAW,OAAO;IAC5C,QAAQ,CAAC,OAAO,EAAE,cAAc,CAAC;;IAMjC;;;;;;;OAOG;YACW,iBAAiB;CAa/B"}
@@ -12,59 +12,72 @@ export interface GraphQLResourceRequestParams {
12
12
  operationName?: string;
13
13
  cacheControl?: CacheControl;
14
14
  /**
15
- * Extra HTTP headers merged over the canonical GraphQL header set on the
16
- * outgoing request. Included in {@link
17
- * HttpGraphQLResourceCacheControlCommand.buildKey} (normalized) because they
18
- * can scope the response — e.g. two identical queries carrying different
19
- * `Authorization` must not share a cache entry, or a later caller could read
20
- * an earlier caller's data without the server re-authorizing.
15
+ * Extra HTTP headers to merge over the canonical GraphQL header set on the
16
+ * outgoing request.
17
+ *
18
+ * @remarks
19
+ * {@link HttpGraphQLResourceCacheControlCommand.buildKey} includes these
20
+ * headers, in normalized form, in the cache key. Headers can scope the
21
+ * response. For example, two identical queries with different
22
+ * `Authorization` values must not share a cache entry. Otherwise a later
23
+ * caller could read an earlier caller's data without the server
24
+ * re-authorizing the request.
21
25
  */
22
26
  headers?: GraphQLRequestHeaders;
23
27
  }
24
28
  type Services = NamedCacheControllerService & Partial<NamedPubSubService> & NamedFetchService;
25
29
  /**
26
- * Per-resource HTTP GraphQL cache-control command.
30
+ * Caches the `data` field of a GraphQL response for one resource.
31
+ *
32
+ * @remarks
33
+ * The cache key combines `query`, `variables`, and `operationName`. Each entry
34
+ * stays valid for {@link DEFAULT_MAX_AGE_SECONDS} seconds. The key uses the
35
+ * raw query string, so semantically identical queries with different
36
+ * formatting produce different cache entries. Callers that want
37
+ * whitespace-equivalent deduplication must normalize the query string before
38
+ * they call this command.
27
39
  *
28
- * Caches the `data` portion of a GraphQL response keyed by `{query, variables,
29
- * operationName}` for {@link DEFAULT_MAX_AGE_SECONDS} seconds. The query is keyed by
30
- * its raw string; semantically identical queries with different formatting produce
31
- * different cache entries. Callers that want whitespace-equivalent deduplication
32
- * should normalize at the call site. Mirrors OneStore's
33
- * `HttpCacheControlCommand` lifecycle (read → fetch → write → re-read) and is intended as
34
- * a building block for higher-level cache integrations rather than a standalone end-user
35
- * API.
40
+ * This command mirrors the read, fetch, write, and re-read lifecycle of
41
+ * OneStore's `HttpCacheControlCommand`. Treat it as a building block for
42
+ * higher-level cache integrations, not as a standalone API for end users.
36
43
  *
37
44
  * ## Caching policy
38
45
  *
39
- * - Successful responses with a non-empty `data` object are cached.
40
- * - Responses where `data` is `null`, missing, or `{}` are NOT cached. An empty `data`
41
- * object usually indicates a transient server condition; caching it would poison the
42
- * cache for the full TTL.
43
- * - Responses with a non-empty `errors` array are surfaced as a `UserVisibleError` and
44
- * are NOT cached. Partial-data preservation (responses carrying both `data` and
45
- * `errors`) is not implemented at this layer; callers requiring it should use a
46
- * higher-level command that overrides `handleCacheControllerResult`.
47
- * - Mutations and subscriptions ARE cached at this layer because operation kind is not
48
- * inspected. Higher-level integrations that route mutations through this command MUST
49
- * bypass it for non-query operations to avoid silent re-issue of cached mutation
50
- * responses.
46
+ * - The command caches a successful response when its `data` object is not
47
+ * empty.
48
+ * - The command does not cache a response when `data` is `null`, missing, or
49
+ * `{}`. An empty `data` object usually signals a temporary server
50
+ * condition. Caching it would poison the cache for the full TTL.
51
+ * - The command does not cache a response with a non-empty `errors` array. It
52
+ * surfaces the response as a `UserVisibleError` instead. This layer does
53
+ * not preserve partial data (a response with both `data` and `errors`).
54
+ * Callers that need partial-data preservation must use a higher-level
55
+ * command that overrides `handleCacheControllerResult`.
56
+ * - This layer does not inspect the operation kind, so it caches mutations
57
+ * and subscriptions too. A higher-level integration that routes mutations
58
+ * through this command must bypass the cache for non-query operations.
59
+ * Otherwise the integration may silently re-issue a cached mutation
60
+ * response.
51
61
  *
52
62
  * ## TTL expiry
53
63
  *
54
- * After the `max-age` window elapses, stale entries are filtered out and
55
- * the next call to `execute()` fetches fresh data from the network.
56
- * Subscribers receive updates via PubSub `cacheUpdate` events when fresh
57
- * data is written back to the cache.
64
+ * After the `max-age` window elapses, the cache filters out the stale entry.
65
+ * The next call to `execute()` then fetches fresh data from the network.
66
+ * Subscribers receive the fresh data through PubSub `cacheUpdate` events when
67
+ * the cache writes the data back.
58
68
  *
59
69
  * ## Variable handling
60
70
  *
61
- * Variables are deep-cloned via `JSON.parse(JSON.stringify(...))` at construction time
62
- * so that subsequent mutation of the caller's object does not desync the cache key from
63
- * the request body. Values that throw inside `JSON.stringify` (circular references,
64
- * BigInt) are rejected at construction with a typed error carrying the operation name.
65
- * Values that silently lose information through the round-trip (`Map`, `Symbol`,
66
- * `function`) are not detected — those would also produce an invalid GraphQL request
67
- * body on the wire path independent of the cache.
71
+ * At construction time, this command deep-clones `variables` with
72
+ * `JSON.parse(JSON.stringify(...))`. This keeps the cache key in sync with
73
+ * the request body even if the caller later mutates the original object.
74
+ *
75
+ * A value that throws inside `JSON.stringify` — a circular reference or a
76
+ * `BigInt` — makes construction fail with a typed error that names the
77
+ * operation. A value that silently loses information through the round trip
78
+ * (`Map`, `Symbol`, or `function`) passes construction unchecked, because it
79
+ * would also produce an invalid GraphQL request body on the wire, regardless
80
+ * of the cache.
68
81
  */
69
82
  export declare class HttpGraphQLResourceCacheControlCommand<TData extends Record<string, unknown> = Record<string, unknown>> extends HttpCacheControlCommand<TData, object, GraphQLResponse<TData>> {
70
83
  private readonly url;
@@ -79,17 +92,18 @@ export declare class HttpGraphQLResourceCacheControlCommand<TData extends Record
79
92
  protected get fetchParams(): Parameters<FetchService>;
80
93
  buildKey(): string;
81
94
  /**
82
- * Reads from the cache and returns the cache result or error
95
+ * Reads the cached result for this command, or returns an error.
83
96
  *
84
- * In case of a missing or partial result, this should return either a DataNotFoundError or
85
- * DataIncompleteError, respectively, in the Error response
97
+ * @remarks
98
+ * When the result is missing or partial, this method returns a
99
+ * `DataNotFoundError` or a `DataIncompleteError` in the error response.
86
100
  *
87
- * Note that any subclass should JUST try to read the data from the cache here; it should
88
- * NOT try to take metadata (eg cache control semantics) into account while reading the
89
- * data. The CacheController is responsible for enforcing those semantics.
101
+ * A subclass must only read data from the cache here. It must not apply
102
+ * metadata, for example cache-control semantics, while it reads the data.
103
+ * The `CacheController` enforces that metadata separately.
90
104
  *
91
- * @param cache source of cached data
92
- * @returns result or error from the cache
105
+ * @param cache - The source of the cached data.
106
+ * @returns The result or error from the cache.
93
107
  */
94
108
  readFromCache(cache: ReadonlyCache): SyncOrAsync<Result<TData, Error>>;
95
109
  writeToCache(cache: Cache, networkResult: Result<GraphQLResponse<TData>, Error>): SyncOrAsync<void>;
@@ -1 +1 @@
1
- {"version":3,"file":"command.d.ts","sourceRoot":"","sources":["../../../../../src/data/shared/graphql/cache/command.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AACH,OAAO,EAAE,uBAAuB,EAAE,MAAM,+CAA+C,CAAC;AACxF,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,4CAA4C,CAAC;AAClF,OAAO,KAAK,EAAE,KAAK,EAAE,aAAa,EAAE,MAAM,kCAAkC,CAAC;AAC7E,OAAO,KAAK,EACX,0BAA0B,EAC1B,2BAA2B,EAC3B,MAAM,0CAA0C,CAAC;AAClD,OAAO,KAAK,EAAE,YAAY,EAAE,iBAAiB,EAAE,MAAM,0CAA0C,CAAC;AAChG,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,mCAAmC,CAAC;AAC5E,OAAO,EAON,KAAK,MAAM,EACX,KAAK,WAAW,EAChB,MAAM,uBAAuB,CAAC;AAC/B,OAAO,KAAK,EAAE,YAAY,EAAE,qBAAqB,EAAE,MAAM,uBAAuB,CAAC;AAuBjF,MAAM,WAAW,4BAA4B;IAC5C,KAAK,EAAE,MAAM,CAAC;IACd,SAAS,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACpC,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,YAAY,CAAC,EAAE,YAAY,CAAC;IAC5B;;;;;;;OAOG;IACH,OAAO,CAAC,EAAE,qBAAqB,CAAC;CAChC;AAED,KAAK,QAAQ,GAAG,2BAA2B,GAAG,OAAO,CAAC,kBAAkB,CAAC,GAAG,iBAAiB,CAAC;AAa9F;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2CG;AACH,qBAAa,sCAAsC,CAClD,KAAK,SAAS,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAC9D,SAAQ,uBAAuB,CAAC,KAAK,EAAE,MAAM,EAAE,eAAe,CAAC,KAAK,CAAC,CAAC;IAYtE,OAAO,CAAC,QAAQ,CAAC,GAAG;IAXrB,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAS;IAC/B,OAAO,CAAC,QAAQ,CAAC,mBAAmB,CAA0B;IAC9D,OAAO,CAAC,QAAQ,CAAC,uBAAuB,CAAS;IACjD,OAAO,CAAC,QAAQ,CAAC,YAAY,CAA2B;IACxD,OAAO,CAAC,QAAQ,CAAC,cAAc,CAAS;IACxC,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAoC;IAC5D,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAqC;gBAG/D,MAAM,EAAE,4BAA4B,EACpC,QAAQ,EAAE,QAAQ,EACD,GAAG,EAAE,MAAM;IAe7B,SAAS,KAAK,WAAW,IAAI,UAAU,CAAC,YAAY,CAAC,CAapD;IAED,QAAQ,IAAI,MAAM;IAelB;;;;;;;;;;;;OAYG;IACH,aAAa,CAAC,KAAK,EAAE,aAAa,GAAG,WAAW,CAAC,MAAM,CAAC,KAAK,EAAE,KAAK,CAAC,CAAC;IAetE,YAAY,CACX,KAAK,EAAE,KAAK,EACZ,aAAa,EAAE,MAAM,CAAC,eAAe,CAAC,KAAK,CAAC,EAAE,KAAK,CAAC,GAClD,WAAW,CAAC,IAAI,CAAC;IAqBpB,SAAS,KAAK,0BAA0B,IAAI,0BAA0B,CAarE;IAED,SAAS,CAAC,iBAAiB,CAAC,IAAI,EAAE,eAAe,CAAC,KAAK,CAAC;cAIrC,uBAAuB,CACzC,IAAI,EAAE,eAAe,CAAC,KAAK,CAAC,GAC1B,MAAM,CAAC,eAAe,CAAC,KAAK,CAAC,EAAE,KAAK,CAAC;CAMxC"}
1
+ {"version":3,"file":"command.d.ts","sourceRoot":"","sources":["../../../../../src/data/shared/graphql/cache/command.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AACH,OAAO,EAAE,uBAAuB,EAAE,MAAM,+CAA+C,CAAC;AACxF,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,4CAA4C,CAAC;AAClF,OAAO,KAAK,EAAE,KAAK,EAAE,aAAa,EAAE,MAAM,kCAAkC,CAAC;AAC7E,OAAO,KAAK,EACX,0BAA0B,EAC1B,2BAA2B,EAC3B,MAAM,0CAA0C,CAAC;AAClD,OAAO,KAAK,EAAE,YAAY,EAAE,iBAAiB,EAAE,MAAM,0CAA0C,CAAC;AAChG,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,mCAAmC,CAAC;AAC5E,OAAO,EAON,KAAK,MAAM,EACX,KAAK,WAAW,EAChB,MAAM,uBAAuB,CAAC;AAC/B,OAAO,KAAK,EAAE,YAAY,EAAE,qBAAqB,EAAE,MAAM,uBAAuB,CAAC;AAuBjF,MAAM,WAAW,4BAA4B;IAC5C,KAAK,EAAE,MAAM,CAAC;IACd,SAAS,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACpC,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,YAAY,CAAC,EAAE,YAAY,CAAC;IAC5B;;;;;;;;;;;OAWG;IACH,OAAO,CAAC,EAAE,qBAAqB,CAAC;CAChC;AAED,KAAK,QAAQ,GAAG,2BAA2B,GAAG,OAAO,CAAC,kBAAkB,CAAC,GAAG,iBAAiB,CAAC;AAa9F;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAoDG;AACH,qBAAa,sCAAsC,CAClD,KAAK,SAAS,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAC9D,SAAQ,uBAAuB,CAAC,KAAK,EAAE,MAAM,EAAE,eAAe,CAAC,KAAK,CAAC,CAAC;IAYtE,OAAO,CAAC,QAAQ,CAAC,GAAG;IAXrB,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAS;IAC/B,OAAO,CAAC,QAAQ,CAAC,mBAAmB,CAA0B;IAC9D,OAAO,CAAC,QAAQ,CAAC,uBAAuB,CAAS;IACjD,OAAO,CAAC,QAAQ,CAAC,YAAY,CAA2B;IACxD,OAAO,CAAC,QAAQ,CAAC,cAAc,CAAS;IACxC,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAoC;IAC5D,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAqC;gBAG/D,MAAM,EAAE,4BAA4B,EACpC,QAAQ,EAAE,QAAQ,EACD,GAAG,EAAE,MAAM;IAe7B,SAAS,KAAK,WAAW,IAAI,UAAU,CAAC,YAAY,CAAC,CAapD;IAED,QAAQ,IAAI,MAAM;IAelB;;;;;;;;;;;;;OAaG;IACH,aAAa,CAAC,KAAK,EAAE,aAAa,GAAG,WAAW,CAAC,MAAM,CAAC,KAAK,EAAE,KAAK,CAAC,CAAC;IAgBtE,YAAY,CACX,KAAK,EAAE,KAAK,EACZ,aAAa,EAAE,MAAM,CAAC,eAAe,CAAC,KAAK,CAAC,EAAE,KAAK,CAAC,GAClD,WAAW,CAAC,IAAI,CAAC;IAqBpB,SAAS,KAAK,0BAA0B,IAAI,0BAA0B,CAarE;IAED,SAAS,CAAC,iBAAiB,CAAC,IAAI,EAAE,eAAe,CAAC,KAAK,CAAC;cAIrC,uBAAuB,CACzC,IAAI,EAAE,eAAe,CAAC,KAAK,CAAC,GAC1B,MAAM,CAAC,eAAe,CAAC,KAAK,CAAC,EAAE,KAAK,CAAC;CAMxC"}
@@ -1 +1 @@
1
- {"version":3,"file":"invoker.d.ts","sourceRoot":"","sources":["../../../../../src/data/shared/graphql/cache/invoker.ts"],"names":[],"mappings":"AAYA,OAAO,KAAK,EAAE,sCAAsC,EAAE,MAAM,WAAW,CAAC;AACxE,OAAO,KAAK,EAAgB,WAAW,EAAmB,MAAM,uBAAuB,CAAC;AAuDxF,wBAAsB,qBAAqB,CAAC,CAAC,EAC5C,OAAO,EAAE,sCAAsC,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,EACxE,YAAY,UAAQ,GAClB,OAAO,CAAC,WAAW,CAAC,CAAC,CAAC,CAAC,CAsCzB"}
1
+ {"version":3,"file":"invoker.d.ts","sourceRoot":"","sources":["../../../../../src/data/shared/graphql/cache/invoker.ts"],"names":[],"mappings":"AAYA,OAAO,KAAK,EAAE,sCAAsC,EAAE,MAAM,WAAW,CAAC;AACxE,OAAO,KAAK,EAAgB,WAAW,EAAmB,MAAM,uBAAuB,CAAC;AA4DxF,wBAAsB,qBAAqB,CAAC,CAAC,EAC5C,OAAO,EAAE,sCAAsC,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,EACxE,YAAY,UAAQ,GAClB,OAAO,CAAC,WAAW,CAAC,CAAC,CAAC,CAAC,CAuCzB"}
@@ -3,8 +3,12 @@ import { NamedCacheControllerService } from '@conduit-client/service-cache-contr
3
3
  import { FetchService, NamedFetchService } from '@conduit-client/service-fetch-network/v1';
4
4
  import { NamedPubSubService } from '@conduit-client/service-pubsub/v1';
5
5
  /**
6
- * Aggregate of OneStore services required by the per-resource HTTP GraphQL
7
- * cache-control command. Internal to WebAppDataSDK; not part of the public API.
6
+ * The OneStore services that the per-resource HTTP GraphQL cache-control
7
+ * command requires.
8
+ *
9
+ * @remarks
10
+ * This type is internal to `WebAppDataSDK`. It is not part of the public
11
+ * API.
8
12
  */
9
13
  export type CacheServices = NamedCacheControllerService & NamedPubSubService & NamedFetchService;
10
14
  export interface SharedCacheBundle {
@@ -17,18 +21,24 @@ export interface CacheBundle {
17
21
  services: CacheServices;
18
22
  }
19
23
  /**
20
- * Module-level registry so all SDK instances targeting the same host+version
21
- * share one cache + cacheController + pubSub — no redundant network
22
- * requests for identical queries across features.
23
- * Exported for test isolation only; not part of the public API.
24
+ * A module-level registry. All SDK instances that target the same host and
25
+ * version share one `cache`, `cacheController`, and `pubSub` instance.
26
+ *
27
+ * @remarks
28
+ * This sharing avoids redundant network requests for identical queries
29
+ * across features. The registry is exported for test isolation only; it is
30
+ * not part of the public API.
24
31
  */
25
32
  export declare const cacheBundleRegistry: Map<string, SharedCacheBundle>;
26
33
  /**
27
- * Returns a CacheBundle for the given cacheKey. The shared cache infra (cache,
28
- * cacheController, pubSub) is deduplicated by cacheKey — instances with the
29
- * same key share cache state, while distinct keys get isolated stores. The
30
- * per-instance networkFetch ensures cache misses route through the calling
31
- * SDK's fetch pipeline (CSRF, onStatus callbacks).
34
+ * Returns a `CacheBundle` for the given `cacheKey`.
35
+ *
36
+ * @remarks
37
+ * This function deduplicates the shared cache infrastructure (`cache`,
38
+ * `cacheController`, `pubSub`) by `cacheKey`. Instances with the same key
39
+ * share cache state; instances with different keys get isolated stores. The
40
+ * per-instance `networkFetch` routes cache misses through the calling SDK's
41
+ * own fetch pipeline, so CSRF handling and `onStatus` callbacks still run.
32
42
  */
33
43
  export declare function buildCacheServices(cacheKey: string, networkFetch: FetchService): CacheBundle;
34
44
  //# sourceMappingURL=services.d.ts.map
@@ -1 +1 @@
1
- {"version":3,"file":"services.d.ts","sourceRoot":"","sources":["../../../../../src/data/shared/graphql/cache/services.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AACH,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,kCAAkC,CAAC;AAE9D,OAAO,KAAK,EAAE,2BAA2B,EAAE,MAAM,0CAA0C,CAAC;AAG5F,OAAO,KAAK,EAAE,YAAY,EAAE,iBAAiB,EAAE,MAAM,0CAA0C,CAAC;AAChG,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,mCAAmC,CAAC;AAG5E;;;GAGG;AACH,MAAM,MAAM,aAAa,GAAG,2BAA2B,GAAG,kBAAkB,GAAG,iBAAiB,CAAC;AAEjG,MAAM,WAAW,iBAAiB;IACjC,KAAK,EAAE,KAAK,CAAC;IACb,eAAe,EAAE,2BAA2B,CAAC,iBAAiB,CAAC,CAAC;IAChE,MAAM,EAAE,kBAAkB,CAAC,QAAQ,CAAC,CAAC;CACrC;AAED,MAAM,WAAW,WAAW;IAC3B,MAAM,EAAE,iBAAiB,CAAC;IAC1B,QAAQ,EAAE,aAAa,CAAC;CACxB;AAED;;;;;GAKG;AACH,eAAO,MAAM,mBAAmB,gCAAuC,CAAC;AAexE;;;;;;GAMG;AACH,wBAAgB,kBAAkB,CAAC,QAAQ,EAAE,MAAM,EAAE,YAAY,EAAE,YAAY,GAAG,WAAW,CAU5F"}
1
+ {"version":3,"file":"services.d.ts","sourceRoot":"","sources":["../../../../../src/data/shared/graphql/cache/services.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AACH,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,kCAAkC,CAAC;AAE9D,OAAO,KAAK,EAAE,2BAA2B,EAAE,MAAM,0CAA0C,CAAC;AAG5F,OAAO,KAAK,EAAE,YAAY,EAAE,iBAAiB,EAAE,MAAM,0CAA0C,CAAC;AAChG,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,mCAAmC,CAAC;AAG5E;;;;;;;GAOG;AACH,MAAM,MAAM,aAAa,GAAG,2BAA2B,GAAG,kBAAkB,GAAG,iBAAiB,CAAC;AAEjG,MAAM,WAAW,iBAAiB;IACjC,KAAK,EAAE,KAAK,CAAC;IACb,eAAe,EAAE,2BAA2B,CAAC,iBAAiB,CAAC,CAAC;IAChE,MAAM,EAAE,kBAAkB,CAAC,QAAQ,CAAC,CAAC;CACrC;AAED,MAAM,WAAW,WAAW;IAC3B,MAAM,EAAE,iBAAiB,CAAC;IAC1B,QAAQ,EAAE,aAAa,CAAC;CACxB;AAED;;;;;;;;GAQG;AACH,eAAO,MAAM,mBAAmB,gCAAuC,CAAC;AAexE;;;;;;;;;GASG;AACH,wBAAgB,kBAAkB,CAAC,QAAQ,EAAE,MAAM,EAAE,YAAY,EAAE,YAAY,GAAG,WAAW,CAU5F"}
@@ -5,12 +5,17 @@ interface BuildCachedGraphQLOptions {
5
5
  bundle: CacheBundle;
6
6
  url: string;
7
7
  executeRaw: RawGraphQLExecutor;
8
+ /** Fill in surface header defaults once, so key and wire share the same headers. */
9
+ resolveEffectiveHeaders?: (headers?: HeadersInit) => HeadersInit | undefined;
8
10
  }
9
11
  /**
10
- * Build the `graphql` namespace for a webapp-surface DataSDK. Owns the cache
11
- * bundle for the lifetime of the SDK instance; queries hit the OneStore
12
- * cache, mutations bypass it via `executeRaw`.
12
+ * Builds the `graphql` namespace for a webapp-surface DataSDK.
13
+ *
14
+ * @remarks
15
+ * This function owns the cache bundle for the lifetime of the SDK instance.
16
+ * A query hits the OneStore cache. A mutation bypasses the cache and runs
17
+ * through `executeRaw` instead.
13
18
  */
14
- export declare function buildCachedGraphQL({ bundle, url, executeRaw, }: BuildCachedGraphQLOptions): DataSDKGraphQL;
19
+ export declare function buildCachedGraphQL({ bundle, url, executeRaw, resolveEffectiveHeaders, }: BuildCachedGraphQLOptions): DataSDKGraphQL;
15
20
  export {};
16
21
  //# sourceMappingURL=cached-graphql.d.ts.map
@@ -1 +1 @@
1
- {"version":3,"file":"cached-graphql.d.ts","sourceRoot":"","sources":["../../../../src/data/shared/graphql/cached-graphql.ts"],"names":[],"mappings":"AAQA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,kBAAkB,CAAC;AACpD,OAAO,EAON,KAAK,kBAAkB,EACvB,MAAM,iBAAiB,CAAC;AACzB,OAAO,KAAK,EAAE,cAAc,EAA2C,MAAM,eAAe,CAAC;AAE7F,UAAU,yBAAyB;IAClC,MAAM,EAAE,WAAW,CAAC;IACpB,GAAG,EAAE,MAAM,CAAC;IACZ,UAAU,EAAE,kBAAkB,CAAC;CAC/B;AAWD;;;;GAIG;AACH,wBAAgB,kBAAkB,CAAC,EAClC,MAAM,EACN,GAAG,EACH,UAAU,GACV,EAAE,yBAAyB,GAAG,cAAc,CA8C5C"}
1
+ {"version":3,"file":"cached-graphql.d.ts","sourceRoot":"","sources":["../../../../src/data/shared/graphql/cached-graphql.ts"],"names":[],"mappings":"AAQA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,kBAAkB,CAAC;AACpD,OAAO,EAON,KAAK,kBAAkB,EACvB,MAAM,iBAAiB,CAAC;AACzB,OAAO,KAAK,EAAE,cAAc,EAA2C,MAAM,eAAe,CAAC;AAE7F,UAAU,yBAAyB;IAClC,MAAM,EAAE,WAAW,CAAC;IACpB,GAAG,EAAE,MAAM,CAAC;IACZ,UAAU,EAAE,kBAAkB,CAAC;IAC/B,oFAAoF;IACpF,uBAAuB,CAAC,EAAE,CAAC,OAAO,CAAC,EAAE,WAAW,KAAK,WAAW,GAAG,SAAS,CAAC;CAC7E;AAWD;;;;;;;GAOG;AACH,wBAAgB,kBAAkB,CAAC,EAClC,MAAM,EACN,GAAG,EACH,UAAU,EACV,uBAAuB,GACvB,EAAE,yBAAyB,GAAG,cAAc,CAiD5C"}
@@ -4,9 +4,12 @@ import { GraphQLError, GraphQLRawDocument, GraphQLRequest, GraphQLResponse, Muta
4
4
  export declare const NOOP_UNSUB: Unsubscribe;
5
5
  export declare const NOOP_REFRESH: () => Promise<void>;
6
6
  /**
7
- * Parse an operation source string into a DocumentNode via the OneStore parser.
8
- * Parse failures are returned as a structured error so callers can surface
9
- * them through `result.errors` rather than throwing.
7
+ * Parses an operation source string into a `DocumentNode` with the OneStore
8
+ * parser.
9
+ *
10
+ * @remarks
11
+ * This function returns a parse failure as a structured error, so callers
12
+ * can surface it through `result.errors` instead of a thrown exception.
10
13
  */
11
14
  export declare function parseToDocument(op: GraphQLRawDocument): Result<DocumentNode, GraphQLError[]>;
12
15
  export declare function getOperationKind(document: DocumentNode, operationName?: string): "query" | "mutation" | "subscription" | "unknown";
@@ -1 +1 @@
1
- {"version":3,"file":"graphql-parse.d.ts","sourceRoot":"","sources":["../../../../src/data/shared/graphql/graphql-parse.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AACH,OAAO,EAGN,KAAK,YAAY,EAEjB,MAAM,4CAA4C,CAAC;AACpD,OAAO,EAAW,KAAK,MAAM,EAAE,MAAM,uBAAuB,CAAC;AAC7D,OAAO,KAAK,EACX,YAAY,EACZ,kBAAkB,EAClB,cAAc,EACd,eAAe,EACf,aAAa,EACb,cAAc,EACd,WAAW,EACX,MAAM,eAAe,CAAC;AAEvB,eAAO,MAAM,UAAU,EAAE,WAExB,CAAC;AAEF,eAAO,MAAM,YAAY,QAAa,OAAO,CAAC,IAAI,CAEjD,CAAC;AAEF;;;;GAIG;AACH,wBAAgB,eAAe,CAAC,EAAE,EAAE,kBAAkB,GAAG,MAAM,CAAC,YAAY,EAAE,YAAY,EAAE,CAAC,CAM5F;AAED,wBAAgB,gBAAgB,CAC/B,QAAQ,EAAE,YAAY,EACtB,aAAa,CAAC,EAAE,MAAM,GACpB,OAAO,GAAG,UAAU,GAAG,cAAc,GAAG,SAAS,CAanD;AAED,wBAAgB,QAAQ,CAAC,MAAM,EAAE,OAAO,GAAG,YAAY,EAAE,CAiBxD;AAED;;;;;;GAMG;AACH,MAAM,MAAM,kBAAkB,GAAG,CAAC,CAAC,EAAE,CAAC,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC/D,OAAO,EAAE,cAAc,CAAC,CAAC,CAAC,EAC1B,SAAS,EAAE,OAAO,GAAG,UAAU,KAC3B,OAAO,CAAC,eAAe,CAAC,CAAC,CAAC,CAAC,CAAC;AAEjC,wBAAsB,aAAa,CAAC,CAAC,EAAE,CAAC,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EACjE,UAAU,EAAE,kBAAkB,EAC9B,EAAE,QAAQ,EAAE,EAAE,EAAE,SAAS,EAAE,aAAa,EAAE,YAAY,EAAE,OAAO,EAAE,EAAE,aAAa,CAAC,CAAC,CAAC,GACjF,OAAO,CAAC,cAAc,CAAC,CAAC,CAAC,CAAC,CAiC5B"}
1
+ {"version":3,"file":"graphql-parse.d.ts","sourceRoot":"","sources":["../../../../src/data/shared/graphql/graphql-parse.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AACH,OAAO,EAGN,KAAK,YAAY,EAEjB,MAAM,4CAA4C,CAAC;AACpD,OAAO,EAAW,KAAK,MAAM,EAAE,MAAM,uBAAuB,CAAC;AAC7D,OAAO,KAAK,EACX,YAAY,EACZ,kBAAkB,EAClB,cAAc,EACd,eAAe,EACf,aAAa,EACb,cAAc,EACd,WAAW,EACX,MAAM,eAAe,CAAC;AAEvB,eAAO,MAAM,UAAU,EAAE,WAExB,CAAC;AAEF,eAAO,MAAM,YAAY,QAAa,OAAO,CAAC,IAAI,CAEjD,CAAC;AAEF;;;;;;;GAOG;AACH,wBAAgB,eAAe,CAAC,EAAE,EAAE,kBAAkB,GAAG,MAAM,CAAC,YAAY,EAAE,YAAY,EAAE,CAAC,CAM5F;AAED,wBAAgB,gBAAgB,CAC/B,QAAQ,EAAE,YAAY,EACtB,aAAa,CAAC,EAAE,MAAM,GACpB,OAAO,GAAG,UAAU,GAAG,cAAc,GAAG,SAAS,CAanD;AAED,wBAAgB,QAAQ,CAAC,MAAM,EAAE,OAAO,GAAG,YAAY,EAAE,CAiBxD;AAED;;;;;;GAMG;AACH,MAAM,MAAM,kBAAkB,GAAG,CAAC,CAAC,EAAE,CAAC,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC/D,OAAO,EAAE,cAAc,CAAC,CAAC,CAAC,EAC1B,SAAS,EAAE,OAAO,GAAG,UAAU,KAC3B,OAAO,CAAC,eAAe,CAAC,CAAC,CAAC,CAAC,CAAC;AAEjC,wBAAsB,aAAa,CAAC,CAAC,EAAE,CAAC,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EACjE,UAAU,EAAE,kBAAkB,EAC9B,EAAE,QAAQ,EAAE,EAAE,EAAE,SAAS,EAAE,aAAa,EAAE,YAAY,EAAE,OAAO,EAAE,EAAE,aAAa,CAAC,CAAC,CAAC,GACjF,OAAO,CAAC,cAAc,CAAC,CAAC,CAAC,CAAC,CAiC5B"}
@@ -4,44 +4,51 @@
4
4
  * For full license text, see the LICENSE.txt file
5
5
  */
6
6
  /**
7
- * Merge caller-supplied `overrides` over a `base` header set — caller wins on
8
- * collision — and return a plain header record suitable for `RequestInit`.
7
+ * Merges caller-supplied `overrides` over a `base` header set and returns a
8
+ * plain header record for `RequestInit`. The caller wins on collision.
9
9
  *
10
+ * @remarks
10
11
  * `overrides` accepts any `HeadersInit` form: a plain record, an array of
11
- * `[name, value]` tuples, or a `Headers` instance. Multi-valued headers are
12
- * expressible via repeated tuple names (folded here into one comma-separated
13
- * value) or a pre-built `Headers`.
12
+ * `[name, value]` tuples, or a `Headers` instance. A caller can express a
13
+ * multi-valued header with repeated tuple names (folded here into one
14
+ * comma-separated value) or with a pre-built `Headers` instance.
14
15
  *
15
- * With no overrides the `base` record is returned by value, unchanged. Header
16
- * names are matched case-insensitively (they are case-insensitive per RFC 7230
17
- * §3.2), so a caller-supplied `content-type` overrides the canonical
18
- * `Content-Type` in place rather than emitting a duplicate. The winning name's
19
- * original casing is preserved — the base key on collision, otherwise the
20
- * caller's.
16
+ * With no overrides, this function returns the `base` record unchanged, by
17
+ * value. Header names are matched case-insensitively, per RFC 7230 §3.2. So a
18
+ * caller-supplied `content-type` overrides the canonical `Content-Type` in
19
+ * place, instead of adding a duplicate. The winning name keeps its original
20
+ * casing: the base key's casing on collision, otherwise the caller's casing.
21
21
  */
22
22
  export declare function mergeRequestHeaders(base: Record<string, string>, overrides?: HeadersInit): Record<string, string>;
23
23
  /**
24
24
  * Builds the canonical Salesforce GraphQL request headers for the core/webapp
25
- * surface, with optional per-request `overrides` merged on top. Used by both
26
- * the WebApp DataSDK transport path and the cache control command so the wire
27
- * format stays identical regardless of which path a consumer's request takes.
25
+ * surface, with optional per-request `overrides` merged on top.
26
+ *
27
+ * @remarks
28
+ * Both the WebApp DataSDK transport path and the cache-control command use
29
+ * this function, so the wire format stays identical no matter which path a
30
+ * consumer's request takes.
28
31
  */
29
32
  export declare function buildGraphQLRequestHeaders(overrides?: HeadersInit): Record<string, string>;
30
33
  /**
31
- * Reduce a per-request `HeadersInit` into a stable, canonical record for use as
32
- * part of a cache key. Any `HeadersInit` form collapses to the same result:
33
- * names are lowercased and repeated names folded (via `Headers`), so callers
34
- * passing equivalent headers in different shapes, casing, or order key
35
- * identically. Returns `undefined` when there are no headers, so the no-header
36
- * path keeps a cache key byte-identical to one built with no headers at all.
34
+ * Reduces a per-request `HeadersInit` value into a stable, canonical record
35
+ * for use in a cache key.
36
+ *
37
+ * @remarks
38
+ * Every `HeadersInit` form collapses to the same result: this function
39
+ * lowercases the names and folds repeated names with `Headers`. So callers
40
+ * that pass equivalent headers in different shapes, casing, or order produce
41
+ * the same key. This function returns `undefined` when there are no
42
+ * headers, so the no-header path keeps a cache key byte-identical to one
43
+ * built with no headers at all.
37
44
  *
38
- * Headers participate in cache identity because they can scope the response —
39
- * most importantly `Authorization`. Two otherwise-identical queries carrying
40
- * different auth must resolve to different cache entries; sharing one would let
41
- * a later caller read an earlier caller's response without the server ever
42
- * re-authorizing (a silent cross-auth data leak). See {@link
43
- * mergeRequestHeaders} for the outgoing-request merge, which is separate from
44
- * this keying concern.
45
+ * Headers take part in cache identity because they can scope the response —
46
+ * most importantly `Authorization`. Two otherwise-identical queries with
47
+ * different auth must resolve to different cache entries. Sharing one entry
48
+ * would let a later caller read an earlier caller's response without the
49
+ * server re-authorizing the request — a silent cross-auth data leak. See
50
+ * {@link mergeRequestHeaders} for the outgoing-request merge, which is a
51
+ * separate concern from this cache-key concern.
45
52
  */
46
53
  export declare function normalizeHeadersForKey(headers?: HeadersInit): Record<string, string> | undefined;
47
54
  //# sourceMappingURL=headers.d.ts.map
@@ -1 +1 @@
1
- {"version":3,"file":"headers.d.ts","sourceRoot":"","sources":["../../../../src/data/shared/graphql/headers.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AA6BH;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,mBAAmB,CAClC,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,EAC5B,SAAS,CAAC,EAAE,WAAW,GACrB,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CA+BxB;AAED;;;;;GAKG;AACH,wBAAgB,0BAA0B,CAAC,SAAS,CAAC,EAAE,WAAW,GAAG,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAE1F;AAED;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,sBAAsB,CAAC,OAAO,CAAC,EAAE,WAAW,GAAG,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,GAAG,SAAS,CAOhG"}
1
+ {"version":3,"file":"headers.d.ts","sourceRoot":"","sources":["../../../../src/data/shared/graphql/headers.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAmCH;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,mBAAmB,CAClC,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,EAC5B,SAAS,CAAC,EAAE,WAAW,GACrB,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAgCxB;AAED;;;;;;;;GAQG;AACH,wBAAgB,0BAA0B,CAAC,SAAS,CAAC,EAAE,WAAW,GAAG,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAE1F;AAED;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAgB,sBAAsB,CAAC,OAAO,CAAC,EAAE,WAAW,GAAG,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,GAAG,SAAS,CAOhG"}
@@ -1,14 +1,16 @@
1
1
  import { GraphQLResponse } from '../../../core';
2
2
  /**
3
- * Thrown when a GraphQL transport response body cannot be parsed as JSON.
3
+ * The error thrown when a GraphQL transport response body cannot be parsed
4
+ * as JSON.
4
5
  *
5
- * The raw `JSON.parse` failure ("Unexpected end of JSON input", "Unexpected
6
- * token < in JSON at position 0", …) is a bare engine message with no transport
7
- * context, so a caller who surfaces it — via `toErrors` in `../graphql-parse`,
8
- * into `result.errors` — has nothing to act on. This error keeps the surface,
9
- * request URL, HTTP status, and a bounded body snippet on the message (and the
10
- * original parse failure as `cause`) so the failure is diagnosable from the
11
- * error text alone.
6
+ * @remarks
7
+ * A raw `JSON.parse` failure, for example "Unexpected end of JSON input" or
8
+ * "Unexpected token < in JSON at position 0", is a bare engine message with
9
+ * no transport context. A caller who surfaces that message — with
10
+ * `toErrors` in `../graphql-parse`, into `result.errors` — has nothing to
11
+ * act on. This error keeps the surface, request URL, HTTP status, and a
12
+ * bounded body snippet on the message, and keeps the original parse failure
13
+ * as `cause`. So the failure is diagnosable from the error text alone.
12
14
  */
13
15
  export declare class GraphQLTransportError extends Error {
14
16
  readonly status: number;
@@ -22,25 +24,31 @@ export declare class GraphQLTransportError extends Error {
22
24
  });
23
25
  }
24
26
  /**
25
- * Parse a raw GraphQL transport {@link Response} into a {@link GraphQLResponse},
26
- * replacing an unguarded `res.json()`.
27
+ * Parses a raw GraphQL transport {@link Response} into a {@link
28
+ * GraphQLResponse}. Replaces an unguarded `res.json()` call.
27
29
  *
30
+ * @remarks
28
31
  * A non-2xx response can still carry a valid GraphQL error body (`{ errors:
29
- * [...] }`), so this does NOT gate on `res.ok`: the body is read and parsed
30
- * regardless of status, and a successfully parsed body is returned as-is. Only
31
- * when the body is empty, not valid JSON, or valid JSON that is not an object
32
- * (a bare scalar or `null`) — the cases that otherwise surface as the
33
- * contextless "Unexpected end of JSON input" downstream, or escape as a
34
- * `TypeError` when a caller reads `.data`/`.errors` off a non-object — is a
35
- * {@link GraphQLTransportError} thrown carrying the surface, URL, status, and a
36
- * body snippet.
32
+ * [...] }`). So this function does not gate on `res.ok`: it reads and parses
33
+ * the body regardless of status, and returns a successfully parsed body
34
+ * as-is.
37
35
  *
38
- * The body is read once via `res.text()` (rather than `res.json()`) so the raw
39
- * text is available for the diagnostic snippet on parse failure.
36
+ * This function throws a {@link GraphQLTransportError} only when the body
37
+ * is empty, is not valid JSON, or is valid JSON that is not an object (a
38
+ * bare scalar or `null`). Otherwise, one of those cases would surface
39
+ * downstream as the contextless "Unexpected end of JSON input" message, or
40
+ * escape as a `TypeError` when a caller reads `.data` or `.errors` off a
41
+ * non-object value. The thrown error carries the surface, URL, status, and
42
+ * a body snippet.
40
43
  *
41
- * @param res the fetch response for a GraphQL POST
42
- * @param surface human-readable transport surface, e.g. `"WebApp"` / `"Mosaic"`
43
- * @param url the request URL, for the diagnostic message
44
+ * This function reads the body once with `res.text()`, instead of
45
+ * `res.json()`, so the raw text is available for the diagnostic snippet if
46
+ * parsing fails.
47
+ *
48
+ * @param res - The fetch response for a GraphQL POST request.
49
+ * @param surface - The human-readable transport surface, for example
50
+ * `"WebApp"` or `"Mosaic"`.
51
+ * @param url - The request URL, for the diagnostic message.
44
52
  */
45
53
  export declare function parseGraphQLResponse<T>(res: Response, surface: string, url: string): Promise<GraphQLResponse<T>>;
46
54
  //# sourceMappingURL=parse-response.d.ts.map
@@ -1 +1 @@
1
- {"version":3,"file":"parse-response.d.ts","sourceRoot":"","sources":["../../../../src/data/shared/graphql/parse-response.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AACH,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,eAAe,CAAC;AA8BrD;;;;;;;;;;GAUG;AACH,qBAAa,qBAAsB,SAAQ,KAAK;IAC/C,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;gBAET,IAAI,EAAE;QACjB,OAAO,EAAE,MAAM,CAAC;QAChB,GAAG,EAAE,MAAM,CAAC;QACZ,MAAM,EAAE,MAAM,CAAC;QACf,IAAI,EAAE,MAAM,CAAC;QACb,KAAK,EAAE,OAAO,CAAC;KACf;CAeD;AAED;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,wBAAsB,oBAAoB,CAAC,CAAC,EAC3C,GAAG,EAAE,QAAQ,EACb,OAAO,EAAE,MAAM,EACf,GAAG,EAAE,MAAM,GACT,OAAO,CAAC,eAAe,CAAC,CAAC,CAAC,CAAC,CAuB7B"}
1
+ {"version":3,"file":"parse-response.d.ts","sourceRoot":"","sources":["../../../../src/data/shared/graphql/parse-response.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AACH,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,eAAe,CAAC;AAsCrD;;;;;;;;;;;;GAYG;AACH,qBAAa,qBAAsB,SAAQ,KAAK;IAC/C,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;gBAET,IAAI,EAAE;QACjB,OAAO,EAAE,MAAM,CAAC;QAChB,GAAG,EAAE,MAAM,CAAC;QACZ,MAAM,EAAE,MAAM,CAAC;QACf,IAAI,EAAE,MAAM,CAAC;QACb,KAAK,EAAE,OAAO,CAAC;KACf;CAeD;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH,wBAAsB,oBAAoB,CAAC,CAAC,EAC3C,GAAG,EAAE,QAAQ,EACb,OAAO,EAAE,MAAM,EACf,GAAG,EAAE,MAAM,GACT,OAAO,CAAC,eAAe,CAAC,CAAC,CAAC,CAAC,CAyB7B"}