@storystick/client 0.2.0-rc.3 → 0.2.0-rc.5

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/PUBLIC-API.md CHANGED
@@ -1,8 +1,8 @@
1
1
  # @storystick/client API contract
2
2
 
3
- Install this candidate explicitly with `@storystick/client@0.2.0-rc.3` after registry bootstrap and publication. This repository alone does not make the candidate or beta channel available on npm.
3
+ Install this candidate explicitly with `@storystick/client@0.2.0-rc.5` after registry bootstrap and publication. This repository alone does not make the candidate or beta channel available on npm.
4
4
 
5
- Version 0.2.0-rc.3, cohort `sdk-0.2.0-rc.3`. ESM distribution; no CommonJS or universal Edge compatibility is promised.
5
+ Version 0.2.0-rc.5, cohort `sdk-0.2.0-rc.7`. ESM distribution; no CommonJS or universal Edge compatibility is promised.
6
6
 
7
7
  This package is a product integration facade. Reserved contracts are required between SDK packages and must be upgraded with the same cohort. Their public export paths do not promise independent stability.
8
8
 
package/dist/.source-hash CHANGED
@@ -1 +1 @@
1
- 8658badf612513cc5a25cae98ec06dd62445f9653b6cc2701472594e6b8b7328
1
+ afc37ed09e83e62c0c5d75a393c056760e8274d36e1257bf4fdaf7c8f39f11e3
package/dist/index.d.ts CHANGED
@@ -21,3 +21,5 @@ export type { ReferenceDocument, ResolveReferenceOptions, ResolvedReference, } f
21
21
  export type { QueryRouteAccessors, QueryRoutePathAccessor } from './query-builder.js';
22
22
  export type { PublicLocaleOrigins } from './locale-routing.js';
23
23
  export type { SchemaStoryName, RoutableSchemaStoryName, RequestedStoryName, TypedRouteDocument, TypedDocumentRoute, ResolvedRouteForSchema } from './typed-route.js';
24
+ export { preloadQuery } from './query-snapshot.js';
25
+ export type { QuerySnapshot } from './query-snapshot.js';
package/dist/index.js CHANGED
@@ -7,3 +7,4 @@ export { StorystickError, QueryExecutionError } from './errors.js';
7
7
  export { normalizePathname, pathnameToHref, pathnameToSegments, segmentsToPathname, } from './normalize-pathname.js';
8
8
  export { publicHrefForLocale, publishedLocaleHrefs, normalizePublicLocaleOrigins, prefixHref, publicPathnameForLocale, resolveLocalePathname } from './locale-routing.js';
9
9
  export { resolveReference, resolveReferences } from './reference-resolver.js';
10
+ export { preloadQuery } from './query-snapshot.js';
@@ -31,3 +31,4 @@ export * from './hydrate-slice.js';
31
31
  export * from './content-values.js';
32
32
  export { attachPreviewQueryReceipt } from './preview-query-receipt.js';
33
33
  export type { RequestContext, PreviewReadScopeEcho, PreviewProvenanceReadLifecycle, PreviewProvenanceReadLifecycleInput, Transport, TransportRequest, } from './types.js';
34
+ export { readQuerySnapshot } from './query-snapshot.js';
package/dist/internal.js CHANGED
@@ -18,3 +18,4 @@ export { previewAssetDependenciesFromValue } from './preview-frame-dependencies.
18
18
  export * from './hydrate-slice.js';
19
19
  export * from './content-values.js';
20
20
  export { attachPreviewQueryReceipt } from './preview-query-receipt.js';
21
+ export { readQuerySnapshot } from './query-snapshot.js';
@@ -28,6 +28,7 @@ export type InternalClientOptions<TSchema extends QuerySchemaDefinition> = Clien
28
28
  readonly requestContext?: RequestContext;
29
29
  };
30
30
  export interface InternalClientRuntime {
31
+ readonly readServiceIdentity: string;
31
32
  readonly contextEpoch: string;
32
33
  readonly executionHost: QueryExecutionHost;
33
34
  readonly transport: Transport;
@@ -51,7 +51,7 @@ export function bindClientSchemaToAuthority(authority, schema) {
51
51
  defaults: runtime.defaults,
52
52
  localeRouting: runtime.localeRouting,
53
53
  });
54
- const bound = createClientWithTransport(options, runtime.transport);
54
+ const bound = createClientWithTransport(options, runtime.transport, runtime.readServiceIdentity);
55
55
  schemas.set(schema, bound);
56
56
  return bound;
57
57
  }
@@ -95,7 +95,10 @@ function normalizeClientOptions(options) {
95
95
  return options;
96
96
  }
97
97
  /** Schema rebinding reuses authority; only the outer factory selects HTTP. */
98
- function createClientWithTransport(options, sourceTransport) {
98
+ function createClientWithTransport(options, sourceTransport, readServiceIdentity = JSON.stringify([
99
+ options.endpoint ?? options.service?.apiOrigin ?? DEFAULT_SERVICE_CONNECTION.apiOrigin,
100
+ options.deliveryEndpoint ?? options.endpoint ?? options.service?.apiOrigin ?? DEFAULT_SERVICE_CONNECTION.apiOrigin,
101
+ ])) {
99
102
  const transport = {
100
103
  async request(input) {
101
104
  assertProjectMatch(input.expectedProjectId ?? options.projectId, options.projectId);
@@ -188,6 +191,7 @@ function createClientWithTransport(options, sourceTransport) {
188
191
  },
189
192
  };
190
193
  CLIENT_RUNTIMES.set(client, {
194
+ readServiceIdentity,
191
195
  contextEpoch,
192
196
  executionHost,
193
197
  transport,
@@ -0,0 +1,25 @@
1
+ import type { QueryPageInfo, QueryResult } from '@storystick/types/query-contract';
2
+ import { type QueryExecuteOptions } from './query-builder.js';
3
+ import { type Client } from './query-client.js';
4
+ /** A render seed, not an access grant or proof of a browser read. */
5
+ export interface QuerySnapshot<TData, TPageInfo extends QueryPageInfo | null = QueryPageInfo | null> {
6
+ readonly version: 1;
7
+ readonly projectId: string;
8
+ readonly schemaFingerprint: string;
9
+ readonly canonical: string;
10
+ readonly readServiceIdentity: string;
11
+ readonly preview: null | {
12
+ readonly contextId: string;
13
+ readonly revision: number;
14
+ };
15
+ readonly result: QueryResult<TData, TPageInfo>;
16
+ }
17
+ /** Execute once on the server; pass this plain JSON value to useQuery's initialData. */
18
+ export declare function preloadQuery<TData, TPageInfo extends QueryPageInfo | null>(query: {
19
+ compile(): {
20
+ readonly canonical: string;
21
+ };
22
+ execute(options?: QueryExecuteOptions): Promise<QueryResult<TData, TPageInfo>>;
23
+ }, options?: QueryExecuteOptions): Promise<QuerySnapshot<TData, TPageInfo>>;
24
+ /** @internal Validate identity before using an RSC seed in a query store. */
25
+ export declare function readQuerySnapshot<TData, TPageInfo extends QueryPageInfo | null>(snapshot: QuerySnapshot<TData, TPageInfo> | undefined, client: Client, canonical: string): QueryResult<TData, TPageInfo> | undefined;
@@ -0,0 +1,38 @@
1
+ import { assertExactQueryResult } from './errors.js';
2
+ import { rawContentValues, prepareContentValues } from './content-values.js';
3
+ import { getExecutableQueryDescriptor } from './query-builder.js';
4
+ import { getInternalClientRuntime } from './query-client.js';
5
+ /** Execute once on the server; pass this plain JSON value to useQuery's initialData. */
6
+ export async function preloadQuery(query, options) {
7
+ const client = getExecutableQueryDescriptor(query).host.client;
8
+ const context = getInternalClientRuntime(client).requestContext;
9
+ const read = context?.previewReadContext;
10
+ if (context?.previewToken && !read) {
11
+ throw new TypeError('A Preview query snapshot requires a bound read context.');
12
+ }
13
+ const result = await query.execute(options);
14
+ assertExactQueryResult(result);
15
+ // Strip process-local identities and WeakMap receipts deliberately. A mounted
16
+ // browser query obtains its own receipt; serialized data never authorizes I/O.
17
+ return JSON.parse(JSON.stringify({
18
+ version: 1,
19
+ projectId: client.projectId,
20
+ schemaFingerprint: client.schema.fingerprint,
21
+ canonical: query.compile().canonical,
22
+ readServiceIdentity: getInternalClientRuntime(client).readServiceIdentity,
23
+ preview: read ? { contextId: read.contextId, revision: read.revision } : null,
24
+ result: rawContentValues(result),
25
+ }));
26
+ }
27
+ /** @internal Validate identity before using an RSC seed in a query store. */
28
+ export function readQuerySnapshot(snapshot, client, canonical) {
29
+ if (!snapshot)
30
+ return undefined;
31
+ if (snapshot.version !== 1 || snapshot.projectId !== client.projectId ||
32
+ snapshot.schemaFingerprint !== client.schema.fingerprint || snapshot.canonical !== canonical ||
33
+ snapshot.readServiceIdentity !== getInternalClientRuntime(client).readServiceIdentity) {
34
+ throw new TypeError('The query snapshot belongs to a different query, project, schema or service.');
35
+ }
36
+ assertExactQueryResult(snapshot.result);
37
+ return prepareContentValues(snapshot.result, true, snapshot.preview !== null);
38
+ }
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@storystick/client",
3
- "version": "0.2.0-rc.3",
3
+ "version": "0.2.0-rc.5",
4
4
  "license": "FSL-1.1-MIT",
5
5
  "type": "module",
6
6
  "main": "./dist/index.js",
@@ -43,8 +43,8 @@
43
43
  "tag": "beta"
44
44
  },
45
45
  "dependencies": {
46
- "@storystick/media": "0.2.0-rc.3",
47
- "@storystick/types": "0.1.0-rc.3"
46
+ "@storystick/media": "0.2.0-rc.4",
47
+ "@storystick/types": "0.1.0-rc.4"
48
48
  },
49
49
  "devDependencies": {
50
50
  "typescript": "^5.8.2",