@openplanr/protocol 0.10.3 → 0.12.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.
@@ -8,6 +8,10 @@ import {
8
8
  assertDiagramWorkspaceContract,
9
9
  DIAGRAM_REVIEW_SCHEMAS,
10
10
  } from './diagram-review-contracts.mjs';
11
+ import {
12
+ assertEnterpriseJourneyContract,
13
+ ENTERPRISE_JOURNEY_SCHEMAS,
14
+ } from './enterprise-journey-contracts.mjs';
11
15
  import { LARGE_OBJECT_SCHEMAS } from './large-object-contracts.mjs';
12
16
  import {
13
17
  PROTOCOL_V16_CONTRACT_FILES,
@@ -87,6 +91,27 @@ export const PROTOCOL_V117_CONTRACTS = Object.freeze(
87
91
  ),
88
92
  );
89
93
 
94
+ export const PROTOCOL_V119_CONTRACTS = Object.freeze(
95
+ Object.fromEntries(
96
+ Object.keys(ENTERPRISE_JOURNEY_SCHEMAS).map((kind) => [kind, `${kind}.schema.json`]),
97
+ ),
98
+ );
99
+
100
+ export function validateEnterpriseJourneyArtifact(kind, value) {
101
+ try {
102
+ assertEnterpriseJourneyContract(value, kind);
103
+ return [];
104
+ } catch (error) {
105
+ return [
106
+ {
107
+ path: '$',
108
+ rule: 'company-journey-contract',
109
+ detail: error instanceof Error ? error.message : 'Invalid company journey data.',
110
+ },
111
+ ];
112
+ }
113
+ }
114
+
90
115
  const PROTOCOL_CONTRACTS_BY_VERSION = Object.freeze({
91
116
  '1.5.0': PROTOCOL_V15_CONTRACTS,
92
117
  '1.6.0': PROTOCOL_V16_CONTRACTS,
@@ -97,6 +122,7 @@ const PROTOCOL_CONTRACTS_BY_VERSION = Object.freeze({
97
122
  '1.15.0': PROTOCOL_V115_CONTRACTS,
98
123
  '1.16.0': PROTOCOL_V116_CONTRACTS,
99
124
  '1.17.0': PROTOCOL_V117_CONTRACTS,
125
+ '1.19.0': PROTOCOL_V119_CONTRACTS,
100
126
  });
101
127
 
102
128
  /**
package/src/contracts.mjs CHANGED
@@ -20,6 +20,10 @@ import {
20
20
  validateDiagramAuthoringArtifact,
21
21
  } from './diagram-authoring-contracts.mjs';
22
22
  import { ENTERPRISE_SCHEMAS } from './enterprise-contracts.mjs';
23
+ import {
24
+ assertEnterpriseJourneyContract,
25
+ ENTERPRISE_JOURNEY_SCHEMAS,
26
+ } from './enterprise-journey-contracts.mjs';
23
27
  import { PipelineError } from './errors.mjs';
24
28
  import { OPERATE_CONTRACT_CATALOG_V2 } from './generated/contract-catalog-v2.mjs';
25
29
  import { validateJson } from './json-schema.mjs';
@@ -265,6 +269,13 @@ const foundationPaths = {
265
269
  };
266
270
 
267
271
  // Authoring successors are additive; preserve every legacy diagram registration.
272
+ for (const kind of Object.keys(ENTERPRISE_JOURNEY_SCHEMAS)) {
273
+ foundationPaths[kind] = {
274
+ ...foundationPaths[kind],
275
+ '1.19.0': `schemas/v1.19.0/${kind}.schema.json`,
276
+ };
277
+ }
278
+
268
279
  for (const [kind, filename] of Object.entries(DIAGRAM_AUTHORING_CONTRACT_FILES)) {
269
280
  foundationPaths[kind] = { ...foundationPaths[kind], '1.13.0': `schemas/v1.13.0/${filename}` };
270
281
  }
@@ -1235,6 +1246,8 @@ function guidedQuestionnaireCompatibilityErrors(value) {
1235
1246
 
1236
1247
  /** @type {typeof import('./contracts.d.mts').validateProtocolArtifact} */
1237
1248
  export function validateProtocolArtifact(kind, value, { protocolVersion } = {}) {
1249
+ const journeyErrors = validateCompanyJourneyArtifact(kind, value, protocolVersion);
1250
+ if (journeyErrors) return journeyErrors;
1238
1251
  const studioKind = Object.hasOwn(LARGE_OBJECT_SCHEMAS, kind);
1239
1252
  if (studioKind && protocolVersion === '1.17.0') {
1240
1253
  return validateStudioArtifact(kind, value, sharedProtocolSchema(kind, protocolVersion));
@@ -1287,6 +1300,31 @@ export function validateProtocolArtifact(kind, value, { protocolVersion } = {})
1287
1300
  }
1288
1301
  return validateGenericArtifact(kind, value, sharedProtocolSchema(kind, version));
1289
1302
  }
1303
+ function validateCompanyJourneyArtifact(kind, value, protocolVersion) {
1304
+ if (Object.hasOwn(ENTERPRISE_JOURNEY_SCHEMAS, kind)) {
1305
+ try {
1306
+ assertLargeObjectData(value);
1307
+ if (
1308
+ protocolVersion === '1.19.0' ||
1309
+ (!protocolVersion &&
1310
+ Object.getOwnPropertyDescriptor(value ?? {}, 'protocolVersion')?.value === '1.19.0')
1311
+ ) {
1312
+ sharedProtocolSchema(kind, '1.19.0');
1313
+ assertEnterpriseJourneyContract(value, kind);
1314
+ return [];
1315
+ }
1316
+ } catch (error) {
1317
+ return [
1318
+ {
1319
+ path: '$',
1320
+ rule: 'company-journey-contract',
1321
+ detail: error instanceof Error ? error.message : 'Invalid company journey data.',
1322
+ },
1323
+ ];
1324
+ }
1325
+ }
1326
+ return null;
1327
+ }
1290
1328
  function invalidStudioData() {
1291
1329
  return [
1292
1330
  { path: '$', rule: 'studio-protocol-contract', detail: 'Expected bounded inert JSON data.' },
@@ -0,0 +1,331 @@
1
+ import type { EnterpriseReviewAnchorV11 } from './enterprise-resource-contracts.mjs';
2
+ import type { CompanyResourceManifest } from './large-object-contracts.mjs';
3
+ export declare const ENTERPRISE_JOURNEY_PROTOCOL_VERSION: '1.19.0';
4
+ export type EnterpriseJourneyFeature =
5
+ | 'resource-draft'
6
+ | 'resource-publication'
7
+ | 'fixed-guest'
8
+ | 'project-lifecycle'
9
+ | 'review-mentions'
10
+ | 'scoped-pages';
11
+ export interface EnterpriseJourneyEnvelope {
12
+ schemaVersion: '1.0.0';
13
+ protocolVersion: '1.19.0';
14
+ }
15
+ export interface EnterpriseJourneyScope {
16
+ organizationId: string;
17
+ projectId: string;
18
+ }
19
+ export interface EnterpriseJourneyArtifact extends EnterpriseJourneyScope {
20
+ artifactId: string;
21
+ }
22
+ export interface EnterprisePublicationPin {
23
+ revisionId: string;
24
+ contentDigest: string;
25
+ publicationId: string;
26
+ }
27
+ export interface EnterpriseGuestInvitation
28
+ extends EnterpriseJourneyEnvelope,
29
+ EnterpriseJourneyArtifact {
30
+ kind: 'openplanr-enterprise-guest-invitation';
31
+ invitationId: string;
32
+ deliveryOperationId: string;
33
+ inviterId: string;
34
+ recipientId: string;
35
+ role: 'reviewer' | 'viewer';
36
+ binding: 'fixed';
37
+ pin: EnterprisePublicationPin;
38
+ deliveryStatus: 'queued' | 'failed' | 'delivered' | 'expired';
39
+ grantStatus: 'pending' | 'active' | 'denied' | 'revoked';
40
+ createdAt: string;
41
+ expiresAt: string;
42
+ }
43
+ export interface EnterpriseGuestAuthorization
44
+ extends EnterpriseJourneyEnvelope,
45
+ EnterpriseJourneyArtifact {
46
+ kind: 'openplanr-enterprise-guest-authorization';
47
+ authorizationId: string;
48
+ operationId: string;
49
+ invitationId: string;
50
+ actorId: string;
51
+ role: 'reviewer' | 'viewer';
52
+ binding: 'fixed';
53
+ pin: EnterprisePublicationPin;
54
+ status: 'pending' | 'active' | 'denied' | 'revoked';
55
+ lifecycleEpoch: number;
56
+ expiresAt: string;
57
+ receipt?: {
58
+ receiptId: string;
59
+ operationId: string;
60
+ authorizedAt: string;
61
+ publicationHeadAdvanced: false;
62
+ };
63
+ }
64
+ export type EnterpriseCatalogQuery =
65
+ | {
66
+ organizationId: string;
67
+ actorId: string;
68
+ scope: 'projects';
69
+ filter: { status: 'all' | 'active' | 'archived'; search: string };
70
+ }
71
+ | {
72
+ organizationId: string;
73
+ projectId: string;
74
+ actorId: string;
75
+ scope: 'artifacts';
76
+ filter: EnterpriseArtifactFilter;
77
+ }
78
+ | {
79
+ organizationId: string;
80
+ actorId: string;
81
+ scope: 'organization-reviews';
82
+ filter: EnterpriseArtifactFilter;
83
+ };
84
+ export type EnterpriseReviewQuery =
85
+ | {
86
+ organizationId: string;
87
+ projectId: string;
88
+ actorId: string;
89
+ scope: 'project-reviews';
90
+ filter: EnterpriseArtifactFilter;
91
+ }
92
+ | Extract<EnterpriseCatalogQuery, { scope: 'organization-reviews' }>;
93
+ export type EnterprisePageQuery = EnterpriseCatalogQuery | EnterpriseReviewQuery;
94
+ export interface EnterpriseArtifactFilter {
95
+ kind: 'all' | 'diagram' | 'design' | 'artifact';
96
+ contentFormat?:
97
+ | 'all'
98
+ | 'diagram-authoring'
99
+ | 'design-review'
100
+ | 'planning-document'
101
+ | 'generic-artifact';
102
+ status: 'all' | 'active' | 'archived';
103
+ search: string;
104
+ }
105
+ export interface EnterprisePageCursor {
106
+ token: string;
107
+ queryDigest: string;
108
+ }
109
+ export interface EnterpriseProjectPage extends EnterpriseJourneyEnvelope {
110
+ kind: 'openplanr-enterprise-project-page';
111
+ query: Extract<EnterprisePageQuery, { scope: 'projects' }>;
112
+ items: (EnterpriseJourneyScope & {
113
+ slug: string;
114
+ name: string;
115
+ status: 'active' | 'archiving' | 'archived' | 'restoring';
116
+ capabilities: import('./enterprise-contracts.mjs').EnterpriseAction[];
117
+ })[];
118
+ nextCursor: EnterprisePageCursor | null;
119
+ }
120
+ export interface EnterpriseArtifactPage extends EnterpriseJourneyEnvelope {
121
+ kind: 'openplanr-enterprise-artifact-page';
122
+ query: Extract<EnterprisePageQuery, { scope: 'artifacts' }>;
123
+ items: (EnterpriseJourneyArtifact & {
124
+ kind: 'diagram' | 'design' | 'artifact';
125
+ contentFormat: 'diagram-authoring' | 'design-review' | 'planning-document' | 'generic-artifact';
126
+ title: string;
127
+ /** Null until the artifact has a saved revision. */
128
+ revisionId: string | null;
129
+ status: 'active' | 'archived';
130
+ capabilities: import('./enterprise-contracts.mjs').EnterpriseAction[];
131
+ })[];
132
+ nextCursor: EnterprisePageCursor | null;
133
+ }
134
+ export interface EnterpriseReviewProjection extends EnterpriseJourneyEnvelope {
135
+ kind: 'openplanr-enterprise-review-projection';
136
+ query: EnterpriseReviewQuery;
137
+ items: (EnterpriseJourneyArtifact & {
138
+ threadId: string;
139
+ revisionId: string;
140
+ publicationId: string;
141
+ category: 'question' | 'suggestion' | 'change-request' | 'blocker';
142
+ status: 'open' | 'addressed' | 'resolved';
143
+ updatedAt: string;
144
+ })[];
145
+ nextCursor: EnterprisePageCursor | null;
146
+ index: { status: 'current' | 'lagging'; watermark: string };
147
+ }
148
+ export interface EnterpriseReviewMention
149
+ extends EnterpriseJourneyEnvelope,
150
+ EnterpriseJourneyArtifact {
151
+ kind: 'openplanr-enterprise-review-mention';
152
+ operationId: string;
153
+ actorId: string;
154
+ threadId: string;
155
+ anchor: EnterpriseReviewAnchorV11;
156
+ recipients: string[];
157
+ authority: 'notification-only';
158
+ }
159
+ export interface EnterpriseProjectLifecycle
160
+ extends EnterpriseJourneyEnvelope,
161
+ EnterpriseJourneyScope {
162
+ kind: 'openplanr-enterprise-project-lifecycle';
163
+ status: 'active' | 'archiving' | 'archived' | 'restoring';
164
+ version: number;
165
+ epoch: number;
166
+ updatedAt: string;
167
+ operation?: {
168
+ operationId: string;
169
+ action: 'archive' | 'restore';
170
+ expectedVersion: number;
171
+ previousEpoch: number;
172
+ inventoryDigest: string;
173
+ artifactCount: number;
174
+ acknowledgedCount: number;
175
+ acknowledgedInventoryDigest: string | null;
176
+ };
177
+ receipt?: {
178
+ receiptId: string;
179
+ operationId: string;
180
+ action: 'archive' | 'restore';
181
+ version: number;
182
+ epoch: number;
183
+ completedAt: string;
184
+ };
185
+ }
186
+ export interface EnterpriseProjectTransition
187
+ extends EnterpriseJourneyEnvelope,
188
+ EnterpriseJourneyScope {
189
+ kind: 'openplanr-enterprise-project-transition';
190
+ operationId: string;
191
+ actorId: string;
192
+ action: 'archive' | 'restore';
193
+ expectedVersion: number;
194
+ expectedEpoch: number;
195
+ }
196
+ export interface EnterpriseJourneyCapabilities extends EnterpriseJourneyEnvelope {
197
+ kind: 'openplanr-enterprise-journey-capabilities';
198
+ readers: EnterpriseJourneyFeature[];
199
+ writers: EnterpriseJourneyFeature[];
200
+ rollbackFloor: { protocolVersion: '1.19.0'; serviceVersion: string; candidateDigest: string };
201
+ }
202
+ export interface CompanyResourcePreparationV21 {
203
+ schemaVersion: '2.1.0';
204
+ protocolVersion: '1.19.0';
205
+ operationId: string;
206
+ baseRevisionId: string | null;
207
+ manifest: CompanyResourceManifest;
208
+ intent: 'draft' | 'publish';
209
+ expectedVersion: number;
210
+ lifecycleEpoch: number;
211
+ }
212
+ export type CompanyResourceReceiptV21 = EnterpriseJourneyArtifact & {
213
+ schemaVersion: '2.1.0';
214
+ protocolVersion: '1.19.0';
215
+ operationId: string;
216
+ revisionId: string;
217
+ manifestSha256: string;
218
+ contentDigest: string;
219
+ status: 'committed';
220
+ committedAt: string;
221
+ baseRevisionId: string | null;
222
+ version: number;
223
+ lifecycleEpoch: number;
224
+ } & (
225
+ | {
226
+ intent: 'draft';
227
+ effect: { kind: 'draft'; authorHeadRevisionId: string; publicationHeadUnchanged: true };
228
+ }
229
+ | {
230
+ intent: 'publish';
231
+ effect: {
232
+ kind: 'publication';
233
+ authorHeadRevisionId: string;
234
+ publicationId: string;
235
+ publicationRevisionId: string;
236
+ };
237
+ }
238
+ );
239
+ export interface CompanyResourceStatusV21 {
240
+ schemaVersion: '2.1.0';
241
+ protocolVersion: '1.19.0';
242
+ operationId: string;
243
+ revisionId: string;
244
+ manifestSha256: string;
245
+ intent: 'draft' | 'publish';
246
+ lifecycleEpoch: number;
247
+ expiresAt: string;
248
+ status: 'prepared' | 'committed' | 'cancelled' | 'expired';
249
+ receivedChunks: { index: number; sha256: string; byteLength: number }[];
250
+ receipt?: CompanyResourceReceiptV21;
251
+ }
252
+ export interface EnterpriseJourneyContracts {
253
+ 'enterprise-guest-invitation': EnterpriseGuestInvitation;
254
+ 'enterprise-guest-authorization': EnterpriseGuestAuthorization;
255
+ 'enterprise-project-page': EnterpriseProjectPage;
256
+ 'enterprise-artifact-page': EnterpriseArtifactPage;
257
+ 'enterprise-review-projection': EnterpriseReviewProjection;
258
+ 'enterprise-review-mention': EnterpriseReviewMention;
259
+ 'enterprise-project-lifecycle': EnterpriseProjectLifecycle;
260
+ 'enterprise-project-transition': EnterpriseProjectTransition;
261
+ 'enterprise-journey-capabilities': EnterpriseJourneyCapabilities;
262
+ 'company-resource-upload-prepare': CompanyResourcePreparationV21;
263
+ 'company-resource-upload-receipt': CompanyResourceReceiptV21;
264
+ 'company-resource-upload-status': CompanyResourceStatusV21;
265
+ }
266
+ export declare const ENTERPRISE_JOURNEY_READER_REQUIREMENTS: Readonly<
267
+ Record<EnterpriseJourneyFeature, readonly EnterpriseJourneyFeature[]>
268
+ >;
269
+ export declare const ENTERPRISE_JOURNEY_FEATURES: readonly EnterpriseJourneyFeature[];
270
+ export declare const ENTERPRISE_JOURNEY_SCHEMAS: Readonly<
271
+ Record<keyof EnterpriseJourneyContracts, Record<string, unknown>>
272
+ >;
273
+ export declare const ENTERPRISE_GUEST_INVITATION_SCHEMA: Record<string, unknown>;
274
+ export declare const ENTERPRISE_GUEST_AUTHORIZATION_SCHEMA: Record<string, unknown>;
275
+ export declare const ENTERPRISE_ARTIFACT_PAGE_SCHEMA: Record<string, unknown>;
276
+ export declare const ENTERPRISE_PROJECT_PAGE_SCHEMA: Record<string, unknown>;
277
+ export declare const ENTERPRISE_REVIEW_PROJECTION_SCHEMA: Record<string, unknown>;
278
+ export declare const ENTERPRISE_REVIEW_MENTION_SCHEMA: Record<string, unknown>;
279
+ export declare const ENTERPRISE_PROJECT_LIFECYCLE_SCHEMA: Record<string, unknown>;
280
+ export declare const ENTERPRISE_PROJECT_TRANSITION_SCHEMA: Record<string, unknown>;
281
+ export declare const ENTERPRISE_JOURNEY_CAPABILITIES_SCHEMA: Record<string, unknown>;
282
+ export declare const COMPANY_RESOURCE_UPLOAD_PREPARE_V21_SCHEMA: Record<string, unknown>;
283
+ export declare const COMPANY_RESOURCE_UPLOAD_RECEIPT_V21_SCHEMA: Record<string, unknown>;
284
+ export declare const COMPANY_RESOURCE_UPLOAD_STATUS_V21_SCHEMA: Record<string, unknown>;
285
+ export declare function assertEnterpriseJourneyContract<K extends keyof EnterpriseJourneyContracts>(
286
+ value: unknown,
287
+ kind: K,
288
+ ): EnterpriseJourneyContracts[K];
289
+ export declare function assertEnterpriseJourneyContract(
290
+ value: unknown,
291
+ kind: string,
292
+ ): EnterpriseJourneyContracts[keyof EnterpriseJourneyContracts];
293
+ export declare function enterprisePageQueryDigest(value: unknown): string;
294
+ export declare function assertEnterpriseJourneyWrite(
295
+ capabilities: unknown,
296
+ feature: EnterpriseJourneyFeature,
297
+ ): EnterpriseJourneyFeature;
298
+ export declare function assertCompanyResourcePreparationRetry(
299
+ previous: unknown,
300
+ next: unknown,
301
+ ): CompanyResourcePreparationV21;
302
+ export declare function assertEnterpriseMentionRecipients(
303
+ value: unknown,
304
+ authorization: EnterpriseJourneyArtifact & {
305
+ actorId: string;
306
+ revisionId: string;
307
+ recipientIds: string[];
308
+ },
309
+ ): EnterpriseReviewMention;
310
+ export declare function assertEnterpriseFixedGuestAccess(
311
+ value: unknown,
312
+ requested: EnterpriseJourneyArtifact &
313
+ EnterprisePublicationPin & { actorId: string; lifecycleEpoch: number },
314
+ now: string,
315
+ ): EnterprisePublicationPin;
316
+ export declare function enterpriseProjectAdmission(value: unknown, epoch: number): boolean;
317
+
318
+ export declare function assertEnterpriseProjectTransition(
319
+ value: unknown,
320
+ current: unknown,
321
+ ): EnterpriseProjectTransition;
322
+ export declare function assertCompanyResourceCommitReceipt(
323
+ value: unknown,
324
+ preparation: unknown,
325
+ ): CompanyResourceReceiptV21;
326
+
327
+ export declare function assertEnterpriseGuestAuthorizationReceipt(
328
+ value: unknown,
329
+ invitation: unknown,
330
+ now: string,
331
+ ): EnterpriseGuestAuthorization;