@storystick/types 0.1.0-rc.2 → 0.1.0-rc.4

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,13 +1,14 @@
1
1
  # @storystick/types API contract
2
2
 
3
- Install this candidate explicitly with `@storystick/types@0.1.0-rc.2` 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/types@0.1.0-rc.4` after registry bootstrap and publication. This repository alone does not make the candidate or beta channel available on npm.
4
4
 
5
- Version 0.1.0-rc.2, cohort `sdk-0.2.0-rc.2`. ESM distribution; no CommonJS or universal Edge compatibility is promised.
5
+ Version 0.1.0-rc.4, cohort `sdk-0.2.0-rc.7`. ESM distribution; no CommonJS or universal Edge compatibility is promised.
6
6
 
7
7
  This package supports the integration facades; installing it directly is an advanced use. 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
 
9
9
  | Entry | Status |
10
10
  | --- | --- |
11
+ | `./internal/workspace-preview-address` | Reserved SDK contract |
11
12
  | `./internal/private-file-session` | Reserved SDK contract |
12
13
  | `./http-failure` | Supported beta entry |
13
14
  | `./publication` | Supported beta entry |
@@ -47,7 +48,7 @@ This package supports the integration facades; installing it directly is an adva
47
48
  | `./internal/richtext-embeds` | Reserved SDK contract |
48
49
  | `./public-endpoints` | Supported beta entry |
49
50
 
50
- The qualified toolchain is Node 24.19.0 and pnpm 9.15.9. Next uses App Router 15.5.28, Sharp 0.35.5 and React/React DOM 19.2.8; Astro uses 7.4.4 with the Node adapter 11.1.9. Browser delivery is verified by bundling; hosted Preview activation and cross-browser behavior require the staging manual check. Source/CLI are Node tools, server entries belong on the server, and browser entries must never receive a server API key.
51
+ Supported consumer Node versions: `^22.13.0 || ^24.19.0`. The release build toolchain remains Node 24.19.0 and pnpm 9.15.9. Next uses App Router 15.5.28, Sharp 0.35.5 and React/React DOM 19.2.8; Astro uses 7.4.4 with the Node adapter 11.1.9. Browser delivery is verified by bundling; hosted Preview activation and cross-browser behavior require the staging manual check. Source/CLI are Node tools, server entries belong on the server, and browser entries must never receive a server API key.
51
52
 
52
53
  This is a support/tooling contract. It does not independently grant project access or permission to perform effects.
53
54
 
package/README.md CHANGED
@@ -17,5 +17,7 @@ Licensed under [FSL-1.1-MIT](./LICENSE).
17
17
  ## Candidate distribution contract
18
18
 
19
19
  See [PUBLIC-API.md](./PUBLIC-API.md) for supported entries, reserved SDK contracts,
20
- the qualified runtime matrix and the candidate cohort. Upgrade Storystick
21
- packages together.
20
+ the qualified runtime matrix and the candidate cohort. Keep shared contracts
21
+ compatible. Use the [release guide](../../release/README.md) to select the
22
+ packages and consumers that need an update; an independent adapter fix does
23
+ not require republishing every package.
@@ -0,0 +1,9 @@
1
+ /** One DNS label per runtime, including when environments share a wildcard
2
+ * certificate. Addresses identify a route; they never authorize access. */
3
+ export declare function workspacePreviewAddress(origin: string): {
4
+ generation: string;
5
+ namespace: string;
6
+ domain: string;
7
+ connectOrigin: string;
8
+ };
9
+ export declare function workspacePreviewOrigin(generation: string, domain: string, namespace?: string): string;
@@ -0,0 +1,18 @@
1
+ /** One DNS label per runtime, including when environments share a wildcard
2
+ * certificate. Addresses identify a route; they never authorize access. */
3
+ export function workspacePreviewAddress(origin) {
4
+ const url = new URL(origin);
5
+ const match = /^([a-f0-9]{32})(?:-([a-z][a-z0-9-]{0,29}[a-z0-9]|[a-z]))?\.((?:[a-z0-9](?:[a-z0-9-]*[a-z0-9])?\.)+[a-z]{2,})$/.exec(url.hostname);
6
+ if (url.protocol !== 'https:' || url.port || url.username || url.password || url.pathname !== '/' || url.search || url.hash || !match || url.hostname.split('.')[0].length > 63)
7
+ throw Error('Invalid workspace HTTP origin');
8
+ const [, generation, namespace = '', domain] = match;
9
+ return { generation: generation, namespace, domain: domain,
10
+ connectOrigin: `https://connect${namespace ? `-${namespace}` : ''}.${domain}` };
11
+ }
12
+ export function workspacePreviewOrigin(generation, domain, namespace = '') {
13
+ const origin = `https://${generation}${namespace ? `-${namespace}` : ''}.${domain}`;
14
+ const address = workspacePreviewAddress(origin);
15
+ if (address.generation !== generation || address.domain !== domain || address.namespace !== namespace)
16
+ throw Error('Invalid workspace HTTP origin');
17
+ return origin;
18
+ }
@@ -5,9 +5,9 @@ export declare const LIVE_QUERY_MAX_DOCUMENTS = 100;
5
5
  export declare const LIVE_QUERY_MAX_FIELD_PATHS = 256;
6
6
  export declare const LIVE_QUERY_MAX_FIELD_PATH_BYTES = 512;
7
7
  export declare const LIVE_QUERY_MAX_VALUE_DEPTH = 16;
8
- export declare const LIVE_QUERY_MAX_STRING_BYTES: number;
9
8
  /** Leaves framing headroom under the transport's 64 KiB full-message cap. */
10
9
  export declare const LIVE_QUERY_MAX_PROJECTION_BYTES: number;
10
+ export declare const LIVE_QUERY_MAX_STRING_BYTES: number;
11
11
  export type LiveQueryScopeV1 = {
12
12
  readonly kind: 'living';
13
13
  readonly locale: string;
@@ -3,9 +3,11 @@ export const LIVE_QUERY_MAX_DOCUMENTS = 100;
3
3
  export const LIVE_QUERY_MAX_FIELD_PATHS = 256;
4
4
  export const LIVE_QUERY_MAX_FIELD_PATH_BYTES = 512;
5
5
  export const LIVE_QUERY_MAX_VALUE_DEPTH = 16;
6
- export const LIVE_QUERY_MAX_STRING_BYTES = 8 * 1024;
7
6
  /** Leaves framing headroom under the transport's 64 KiB full-message cap. */
8
7
  export const LIVE_QUERY_MAX_PROJECTION_BYTES = 60 * 1024;
8
+ // Rich text is stored as JSON text. It shares the whole projection budget;
9
+ // a smaller leaf limit would reject an otherwise bounded article snapshot.
10
+ export const LIVE_QUERY_MAX_STRING_BYTES = LIVE_QUERY_MAX_PROJECTION_BYTES;
9
11
  /**
10
12
  * Derive the only Query V2 subset eligible for the v1 local overlay.
11
13
  * Filters, sorts and relations stay on the causal path because an edit can
@@ -1,3 +1,16 @@
1
- /** Public routing contracts; deployment-specific URLs remain explicit overrides. */
1
+ /** Production defaults. Alternate services are explicit complete configurations. */
2
2
  export declare const STORYSTICK_GATEWAY_ORIGIN = "https://api.storystick.app";
3
3
  export declare const STORYSTICK_STUDIO_ORIGIN = "https://storystick.app";
4
+ export interface ServiceConnection {
5
+ readonly studioOrigin: string;
6
+ readonly apiOrigin: string;
7
+ readonly syncOrigin: string;
8
+ }
9
+ export declare const DEFAULT_SERVICE_CONNECTION: ServiceConnection;
10
+ /** Origins only; credential-bearing URLs, paths and implicit protocol upgrades are forbidden. */
11
+ export declare function serviceOrigin(value: unknown): string;
12
+ /** Strict projection keeps internal profile fields and secrets out of the browser. */
13
+ export declare function parseServiceConnection(value: unknown): ServiceConnection;
14
+ /** Caller supplies the process environment; this pure helper never reads files. */
15
+ export declare function serviceConnectionFromEnv(env: Record<string, string | undefined>): ServiceConnection | undefined;
16
+ export declare function assertServiceOrigin(actual: string | undefined, expected: string): void;
@@ -1,3 +1,58 @@
1
- /** Public routing contracts; deployment-specific URLs remain explicit overrides. */
1
+ /** Production defaults. Alternate services are explicit complete configurations. */
2
2
  export const STORYSTICK_GATEWAY_ORIGIN = 'https://api.storystick.app';
3
3
  export const STORYSTICK_STUDIO_ORIGIN = 'https://storystick.app';
4
+ export const DEFAULT_SERVICE_CONNECTION = Object.freeze({
5
+ studioOrigin: STORYSTICK_STUDIO_ORIGIN,
6
+ apiOrigin: STORYSTICK_GATEWAY_ORIGIN,
7
+ syncOrigin: 'https://sync.storystick.app',
8
+ });
9
+ /** Origins only; credential-bearing URLs, paths and implicit protocol upgrades are forbidden. */
10
+ export function serviceOrigin(value) {
11
+ if (typeof value !== 'string' || !value || value !== value.trim())
12
+ throw new TypeError('Invalid service origin.');
13
+ let url;
14
+ try {
15
+ url = new URL(value);
16
+ }
17
+ catch {
18
+ throw new TypeError('Invalid service origin.');
19
+ }
20
+ const loopback = url.protocol === 'http:' && ['127.0.0.1', 'localhost', '[::1]'].includes(url.hostname);
21
+ if ((!loopback && url.protocol !== 'https:') || url.username || url.password || url.search || url.hash || url.pathname !== '/') {
22
+ throw new TypeError('Service origins require HTTPS (HTTP loopback is allowed), without credentials, path, query or fragment.');
23
+ }
24
+ return url.origin;
25
+ }
26
+ /** Strict projection keeps internal profile fields and secrets out of the browser. */
27
+ export function parseServiceConnection(value) {
28
+ if (typeof value === 'string') {
29
+ try {
30
+ value = JSON.parse(value);
31
+ }
32
+ catch {
33
+ throw new TypeError('Invalid service configuration JSON.');
34
+ }
35
+ }
36
+ if (!value || typeof value !== 'object' || Array.isArray(value))
37
+ throw new TypeError('Invalid service configuration.');
38
+ const input = value;
39
+ const fields = ['studioOrigin', 'apiOrigin', 'syncOrigin'];
40
+ if (Object.keys(input).length !== fields.length || Object.keys(input).some(key => !fields.includes(key))) {
41
+ throw new TypeError('A complete service configuration requires only Studio, API and sync origins.');
42
+ }
43
+ return Object.freeze({ studioOrigin: serviceOrigin(input.studioOrigin), apiOrigin: serviceOrigin(input.apiOrigin), syncOrigin: serviceOrigin(input.syncOrigin) });
44
+ }
45
+ /** Caller supplies the process environment; this pure helper never reads files. */
46
+ export function serviceConnectionFromEnv(env) {
47
+ if (env.STORYSTICK_ENVIRONMENT !== undefined || env.NEXT_PUBLIC_STORYSTICK_ENVIRONMENT !== undefined) {
48
+ throw new TypeError('Obsolete service selection. Reconnect the project and use the operator launcher for an alternate service.');
49
+ }
50
+ const raw = env.STORYSTICK_SERVICE_CONFIG;
51
+ if (raw !== undefined)
52
+ return parseServiceConnection(raw);
53
+ return undefined;
54
+ }
55
+ export function assertServiceOrigin(actual, expected) {
56
+ if (actual !== undefined && serviceOrigin(actual) !== expected)
57
+ throw new TypeError('Service configuration conflicts with an explicit origin.');
58
+ }
@@ -26,8 +26,16 @@ export interface SchemaChangePlanV1 {
26
26
  changes: SchemaChange[];
27
27
  affectedStoryTypes: string[];
28
28
  affectedDocumentsUpperBound?: number;
29
+ /** Server-proven exception for removing unreferenced, unused document types.
30
+ * Structural classification remains breaking; only a fresh server check can
31
+ * authorize the push. This witness is part of planDigest. */
32
+ directPush?: {
33
+ kind: 'unused-document-removal';
34
+ storyTypes: string[];
35
+ };
29
36
  planDigest: string;
30
37
  }
38
+ export declare function schemaChangeAllowsDirectPush(plan: SchemaChangePlanV1): boolean;
31
39
  /**
32
40
  * JSON values admitted at the schema-migration author boundary. This mirrors
33
41
  * Storystick's canonical JSON contract without importing a serializer or a
@@ -47,6 +55,13 @@ export type SchemaChangeTransformResult = {
47
55
  } | {
48
56
  kind: 'replace';
49
57
  value: SchemaChangeJsonValue;
58
+ } | {
59
+ kind: 'remove';
60
+ }
61
+ /** Move the owned value into a declared field of the same object. */
62
+ | {
63
+ kind: 'move';
64
+ path: string[];
50
65
  } | {
51
66
  kind: 'issue';
52
67
  code: string;
@@ -217,9 +232,23 @@ export interface SchemaChangeReceiptV2 extends Omit<SchemaChangeReceiptV1, 'reci
217
232
  proposalAggregateDigest?: string;
218
233
  recipe?: SchemaChangeRecipeV1;
219
234
  }
220
- export type SchemaChangeReceipt = SchemaChangeReceiptV1 | SchemaChangeReceiptV2;
235
+ export interface ReleaseSchemaChangeReceipt extends Omit<SchemaChangeReceiptV2, 'servingEvidenceId'> {
236
+ releaseId: string;
237
+ reconcile?: boolean;
238
+ mainCheckpoint?: {
239
+ generationId: string;
240
+ schemaVersion: string;
241
+ revision: number;
242
+ };
243
+ }
244
+ export type SchemaChangeReceipt = SchemaChangeReceiptV1 | SchemaChangeReceiptV2 | ReleaseSchemaChangeReceipt;
221
245
  export interface SchemaChangeRunViewV1 {
222
246
  runId: string;
247
+ /** Omitted for project activation. A release run never activates Main/public. */
248
+ releaseId?: string;
249
+ /** Rebuild the release against current Main, preserving its decisions. */
250
+ reconcile?: boolean;
251
+ mainCheckpointCurrent?: boolean;
223
252
  status: SchemaChangeRunStatus;
224
253
  phase: SchemaChangeRunPhase;
225
254
  step: number;
@@ -34,6 +34,20 @@ export function logicalProjectIdFromSchemaChangeStorage(storageProjectId) {
34
34
  return storageProjectId;
35
35
  }
36
36
  }
37
+ export function schemaChangeAllowsDirectPush(plan) {
38
+ if (['unchanged', 'presentation', 'additive'].includes(plan.classification))
39
+ return true;
40
+ if (plan.classification !== 'breaking' || plan.directPush?.kind !== 'unused-document-removal')
41
+ return false;
42
+ const ids = plan.directPush.storyTypes;
43
+ if (!Array.isArray(ids) || ids.length === 0 || ids.some(id => typeof id !== 'string' || !id))
44
+ return false;
45
+ if (!ids.every(id => plan.changes.some(change => change.kind === 'story-removed' && change.path === `stories.${id}`)))
46
+ return false;
47
+ return plan.changes.every(change => change.classification !== 'unknown' && (change.classification !== 'breaking' || ids.some(id => (change.kind === 'story-removed' && change.path === `stories.${id}`) ||
48
+ (change.kind === 'binding-removed' && change.path.startsWith(`fieldBindings.${id}.`)) ||
49
+ (change.kind === 'zone-mapping-changed' && change.path === `zoneMappings.${id}`))));
50
+ }
37
51
  export const SCHEMA_CHANGE_RECIPE_IDS = [
38
52
  'text-to-single-line-richtext',
39
53
  'enum-contract-fixture',
@@ -151,6 +165,19 @@ export function decodeSchemaChangeTransformResult(value, path = 'result') {
151
165
  assertExactKeys(value, ['kind'], path);
152
166
  return { kind: 'unchanged' };
153
167
  }
168
+ if (value.kind === 'remove') {
169
+ assertExactKeys(value, ['kind'], path);
170
+ return { kind: 'remove' };
171
+ }
172
+ if (value.kind === 'move') {
173
+ assertExactKeys(value, ['kind', 'path'], path);
174
+ if (!Array.isArray(value.path) || value.path.length === 0 || value.path.length > 16 ||
175
+ value.path.some(segment => typeof segment !== 'string' || !/^[A-Za-z][A-Za-z0-9_]*$/.test(segment) ||
176
+ ['constructor', 'prototype'].includes(segment))) {
177
+ throw new SchemaChangeContractError(`${path}.path: expected a declared field path`);
178
+ }
179
+ return { kind: 'move', path: [...value.path] };
180
+ }
154
181
  if (value.kind === 'replace') {
155
182
  assertExactKeys(value, ['kind', 'value'], path);
156
183
  return {
package/package.json CHANGED
@@ -1,12 +1,16 @@
1
1
  {
2
2
  "name": "@storystick/types",
3
- "version": "0.1.0-rc.2",
3
+ "version": "0.1.0-rc.4",
4
4
  "license": "FSL-1.1-MIT",
5
5
  "type": "module",
6
6
  "sideEffects": false,
7
7
  "main": "dist/index.js",
8
8
  "types": "dist/index.d.ts",
9
9
  "exports": {
10
+ "./internal/workspace-preview-address": {
11
+ "types": "./dist/internal/workspace-preview-address.d.ts",
12
+ "import": "./dist/internal/workspace-preview-address.js"
13
+ },
10
14
  "./internal/private-file-session": {
11
15
  "types": "./dist/internal/private-file-session.d.ts",
12
16
  "import": "./dist/internal/private-file-session.js"
@@ -177,7 +181,7 @@
177
181
  "@types/node": "^22.13.10"
178
182
  },
179
183
  "engines": {
180
- "node": ">=24.19.0 <25"
184
+ "node": "^22.13.0 || ^24.19.0"
181
185
  },
182
186
  "repository": {
183
187
  "type": "git",