@dakkitor/api-contracts 1.7.0 → 1.8.0

package/dist/relay-pods/relay-hub.contract.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"relay-hub.contract.d.ts","sourceRoot":"","sources":["../../contracts/relay-pods/relay-hub.contract.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAUxB,cAAc,qBAAqB,CAAC;AAqCpC,eAAO,MAAM,gBAAgB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CA0F5B,CAAC"}

package/dist/relay-pods/relay-hub.contract.js

@@ -0,0 +1,140 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.relayHubContract = void 0;
+const core_1 = require("@ts-rest/core");
+const zod_1 = require("zod");
+const error_schemas_1 = require("../common/error-schemas");
+const relay_hub_schemas_1 = require("./relay-hub.schemas");
+__exportStar(require("./relay-hub.schemas"), exports);
+const c = (0, core_1.initContract)();
+const RelayHubSsoCodeIssueBodySchema = zod_1.z
+    .object({
+    state: zod_1.z.string().min(1),
+    nonce: zod_1.z.string().min(1),
+    redirectUri: zod_1.z.string().url(),
+    returnPath: zod_1.z.string().regex(/^\/(?!\/)/),
+})
+    .strict();
+const RelayHubSsoCodeIssueResponseSchema = zod_1.z
+    .object({
+    redirectUrl: zod_1.z.string().url(),
+})
+    .strict();
+const RelayHubSsoCodeExchangeBodySchema = zod_1.z
+    .object({
+    code: zod_1.z.string().min(1),
+})
+    .strict();
+const RelayHubSsoSessionPathParamsSchema = zod_1.z
+    .object({
+    id: zod_1.z.string().uuid(),
+})
+    .strict();
+// Machine credentials are deliberately absent from this router: no controller
+// implements them in this release, and an advertised route that answers 404 is
+// worse than no route at all. Credentials are issued out of band through
+// RelayHubMachineCredentialService (see its bootstrapping note). The credential
+// schemas stay exported from relay-hub.schemas.ts because they describe that
+// service's payloads.
+exports.relayHubContract = c.router({
+    issueAuthorizationCode: {
+        method: 'POST',
+        path: '/sso/codes',
+        body: RelayHubSsoCodeIssueBodySchema,
+        responses: {
+            200: RelayHubSsoCodeIssueResponseSchema,
+        },
+        summary: 'Start a Relay Hub authorization-code exchange',
+        metadata: { tags: ['Relay Hub'] },
+    },
+    exchangeAuthorizationCode: {
+        method: 'POST',
+        path: '/sso/exchange',
+        body: RelayHubSsoCodeExchangeBodySchema,
+        responses: {
+            200: relay_hub_schemas_1.RelayHubAuthorizationProjectionSchema,
+            404: error_schemas_1.ErrorResponseSchema,
+        },
+        summary: 'Exchange a one-time Relay Hub authorization code',
+        metadata: { tags: ['Relay Hub'] },
+    },
+    refreshAuthorization: {
+        method: 'POST',
+        path: '/sso/sessions/:id/refresh',
+        pathParams: RelayHubSsoSessionPathParamsSchema,
+        body: zod_1.z.object({}).strict(),
+        responses: {
+            200: relay_hub_schemas_1.RelayHubAuthorizationProjectionSchema,
+            404: error_schemas_1.ErrorResponseSchema,
+        },
+        summary: 'Refresh a Relay Hub authorization projection',
+        metadata: { tags: ['Relay Hub'] },
+    },
+    revokeAuthorization: {
+        method: 'POST',
+        path: '/sso/sessions/:id/revoke',
+        pathParams: RelayHubSsoSessionPathParamsSchema,
+        body: zod_1.z.object({}).strict(),
+        responses: {
+            200: zod_1.z.object({ revoked: zod_1.z.literal(true) }).strict(),
+            404: error_schemas_1.ErrorResponseSchema,
+        },
+        summary: 'Revoke a Relay Hub authorization session',
+        metadata: { tags: ['Relay Hub'] },
+    },
+    listPods: {
+        method: 'GET',
+        path: '/pods',
+        responses: {
+            200: zod_1.z.array(relay_hub_schemas_1.RelayHubHumanPodProjectionSchema),
+        },
+        summary: 'List Relay Hub pod projections',
+        metadata: { tags: ['Relay Hub'] },
+    },
+    upsertPodProjection: {
+        method: 'PUT',
+        path: '/pods/:id',
+        pathParams: zod_1.z.object({ id: zod_1.z.string().uuid() }).strict(),
+        body: relay_hub_schemas_1.RelayHubPodProjectionMutationSchema,
+        responses: {
+            200: relay_hub_schemas_1.RelayHubPodProjectionSchema,
+            404: error_schemas_1.ErrorResponseSchema,
+            409: error_schemas_1.ErrorResponseSchema,
+        },
+        summary: 'Upsert a Relay Hub pod projection',
+        metadata: { tags: ['Relay Hub'] },
+    },
+    publishFleet: {
+        method: 'PUT',
+        path: '/lab-fleet',
+        body: relay_hub_schemas_1.RelayHubFleetProjectionMutationSchema,
+        responses: {
+            200: relay_hub_schemas_1.RelayHubFleetProjectionMutationSchema,
+            409: error_schemas_1.ErrorResponseSchema,
+        },
+        summary: 'Publish Relay Hub fleet projections',
+        metadata: { tags: ['Relay Hub'] },
+    },
+}, {
+    pathPrefix: '/v3/relay-hub',
+    commonResponses: {
+        400: error_schemas_1.ErrorResponseSchema,
+        401: error_schemas_1.ErrorResponseSchema,
+        403: error_schemas_1.ErrorResponseSchema,
+        500: error_schemas_1.ErrorResponseSchema,
+    },
+});

package/dist/relay-pods/relay-hub.contract.spec.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=relay-hub.contract.spec.d.ts.map

package/dist/relay-pods/relay-hub.contract.spec.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"relay-hub.contract.spec.d.ts","sourceRoot":"","sources":["../../contracts/relay-pods/relay-hub.contract.spec.ts"],"names":[],"mappings":""}

package/dist/relay-pods/relay-hub.contract.spec.js

@@ -0,0 +1,180 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const bun_test_1 = require("bun:test");
+const index_1 = require("../index");
+const relay_pod_sessions_contract_1 = require("./relay-pod-sessions.contract");
+const relay_pods_contract_1 = require("./relay-pods.contract");
+const relay_hub_schemas_1 = require("./relay-hub.schemas");
+const relay_hub_contract_1 = require("./relay-hub.contract");
+const relay_pods_schemas_1 = require("./relay-pods.schemas");
+const podId = '11111111-1111-4111-8111-111111111111';
+const userId = '22222222-2222-4222-8222-222222222222';
+const sessionId = '33333333-3333-4333-8333-333333333333';
+const assertionId = '44444444-4444-4444-8444-444444444444';
+const mutationId = '55555555-5555-4555-8555-555555555555';
+const correlationId = '66666666-6666-4666-8666-666666666666';
+const observedAt = '2026-08-16T10:00:00.000Z';
+const podProjection = {
+    id: podId,
+    slug: 'pod-12',
+    displayName: 'Pod 12',
+    integrationMode: 'HUB',
+    migrationState: 'SHADOW',
+    operationalState: 'OFFLINE',
+    projectionVersion: 1,
+    publicBaseUrl: null,
+    members: [],
+    observedAt,
+};
+const fleetProjection = {
+    fleetVersion: 1,
+    observedAt,
+    devices: [],
+};
+const mutationMetadata = {
+    idempotencyKey: mutationId,
+    correlationId,
+    expectedVersion: 0,
+};
+(0, bun_test_1.describe)('Relay Hub V3 schemas', () => {
+    (0, bun_test_1.it)('preserves unknown legacy operational facts in the human list without weakening machine projections', () => {
+        (0, bun_test_1.expect)(relay_hub_schemas_1.RelayHubHumanPodProjectionSchema.parse({
+            ...podProjection,
+            integrationMode: 'LEGACY',
+            migrationState: 'LEGACY',
+            operationalState: null,
+            observedAt: null,
+        })).toMatchObject({ operationalState: null, observedAt: null });
+        (0, bun_test_1.expect)(relay_hub_schemas_1.RelayHubPodProjectionSchema.safeParse({
+            ...podProjection,
+            operationalState: null,
+            observedAt: null,
+        }).success).toBe(false);
+    });
+    (0, bun_test_1.it)('accepts an unassigned Hub pod without weakening the V2 pod summary', () => {
+        const pod = relay_hub_schemas_1.RelayHubPodProjectionSchema.parse(podProjection);
+        (0, bun_test_1.expect)(pod.members).toEqual([]);
+        const legacyPod = {
+            id: podId,
+            slug: 'pod-12',
+            displayName: 'Pod 12',
+            ownerUserId: userId,
+            ownerName: null,
+            publicBaseUrl: 'https://pod-12.test',
+            status: 'ACTIVE',
+        };
+        (0, bun_test_1.expect)(relay_pods_schemas_1.RelayPodSummarySchema.parse(legacyPod).ownerUserId).toBe(userId);
+        (0, bun_test_1.expect)(relay_pods_schemas_1.RelayPodSummarySchema.safeParse({
+            ...legacyPod,
+            publicBaseUrl: null,
+        }).success).toBe(false);
+        (0, bun_test_1.expect)(relay_pods_schemas_1.RelayPodSummarySchema.safeParse({
+            id: legacyPod.id,
+            slug: legacyPod.slug,
+            displayName: legacyPod.displayName,
+            ownerName: legacyPod.ownerName,
+            publicBaseUrl: legacyPod.publicBaseUrl,
+            status: legacyPod.status,
+        }).success).toBe(false);
+        (0, bun_test_1.expect)(relay_pods_schemas_1.RelayPodSummarySchema.safeParse({
+            ...legacyPod,
+            integrationMode: 'LEGACY',
+        }).success).toBe(false);
+    });
+    (0, bun_test_1.it)('publishes a complete, expiring authorization projection', () => {
+        (0, bun_test_1.expect)(relay_hub_schemas_1.RelayHubAuthorizationProjectionSchema.parse({
+            sessionId,
+            assertionId,
+            user: {
+                id: userId,
+                email: 'operator@example.com',
+                displayName: 'Operator',
+            },
+            impersonatedBy: null,
+            isAdmin: false,
+            assignedPodIds: [podId],
+            rules: [{ action: 'manage', subject: 'RelayPod' }],
+            permissionProjectionVersion: 4,
+            issuedAt: observedAt,
+            expiresAt: '2026-08-16T11:00:00.000Z',
+        }).assignedPodIds).toEqual([podId]);
+    });
+    (0, bun_test_1.it)('composes all mutation metadata into pod and fleet projection request schemas', () => {
+        (0, bun_test_1.expect)(relay_hub_schemas_1.RelayHubFleetProjectionSchema.parse(fleetProjection).devices).toEqual([]);
+        for (const [schema, projection] of [
+            [relay_hub_schemas_1.RelayHubPodProjectionMutationSchema, podProjection],
+            [relay_hub_schemas_1.RelayHubFleetProjectionMutationSchema, fleetProjection],
+        ]) {
+            (0, bun_test_1.expect)(schema.safeParse({ ...projection, ...mutationMetadata }).success).toBe(true);
+            (0, bun_test_1.expect)(schema.safeParse({
+                ...projection,
+                correlationId,
+                expectedVersion: 0,
+            }).success).toBe(false);
+            (0, bun_test_1.expect)(schema.safeParse({
+                ...projection,
+                idempotencyKey: mutationId,
+                expectedVersion: 0,
+            }).success).toBe(false);
+            (0, bun_test_1.expect)(schema.safeParse({
+                ...projection,
+                idempotencyKey: mutationId,
+                correlationId,
+            }).success).toBe(false);
+            (0, bun_test_1.expect)(schema.safeParse({
+                ...projection,
+                ...mutationMetadata,
+                expectedVersion: -1,
+            }).success).toBe(false);
+        }
+    });
+});
+(0, bun_test_1.describe)('relayHubContract routes', () => {
+    (0, bun_test_1.it)('publishes the Hub SSO, projection, and fleet routes under /v3', () => {
+        (0, bun_test_1.expect)(relay_hub_contract_1.relayHubContract.issueAuthorizationCode).toMatchObject({
+            method: 'POST',
+            path: '/v3/relay-hub/sso/codes',
+        });
+        (0, bun_test_1.expect)(relay_hub_contract_1.relayHubContract.exchangeAuthorizationCode).toMatchObject({
+            method: 'POST',
+            path: '/v3/relay-hub/sso/exchange',
+        });
+        (0, bun_test_1.expect)(relay_hub_contract_1.relayHubContract.refreshAuthorization).toMatchObject({
+            method: 'POST',
+            path: '/v3/relay-hub/sso/sessions/:id/refresh',
+        });
+        (0, bun_test_1.expect)(relay_hub_contract_1.relayHubContract.revokeAuthorization).toMatchObject({
+            method: 'POST',
+            path: '/v3/relay-hub/sso/sessions/:id/revoke',
+        });
+        (0, bun_test_1.expect)(relay_hub_contract_1.relayHubContract.listPods).toMatchObject({
+            method: 'GET',
+            path: '/v3/relay-hub/pods',
+        });
+        (0, bun_test_1.expect)(relay_hub_contract_1.relayHubContract.upsertPodProjection).toMatchObject({
+            method: 'PUT',
+            path: '/v3/relay-hub/pods/:id',
+        });
+        (0, bun_test_1.expect)(relay_hub_contract_1.relayHubContract.publishFleet).toMatchObject({
+            method: 'PUT',
+            path: '/v3/relay-hub/lab-fleet',
+        });
+        (0, bun_test_1.expect)(index_1.apiContractRouter.RelayHub.listPods.path).toBe('/v3/relay-hub/pods');
+    });
+    // Machine credentials have no implementing controller in this release, so the
+    // contract must not advertise routes that would answer 404. They are issued
+    // out of band (see RelayHubMachineCredentialService) until a controller ships.
+    (0, bun_test_1.it)('advertises no machine credential routes while none are implemented', () => {
+        const paths = Object.values(relay_hub_contract_1.relayHubContract)
+            .map((route) => route.path)
+            .filter((path) => typeof path === 'string');
+        (0, bun_test_1.expect)(paths).not.toContain('/v3/relay-hub/credentials');
+        (0, bun_test_1.expect)(paths.some((path) => path.startsWith('/v3/relay-hub/credentials'))).toBe(false);
+        (0, bun_test_1.expect)(relay_hub_contract_1.relayHubContract).not.toHaveProperty('createMachineCredential');
+        (0, bun_test_1.expect)(relay_hub_contract_1.relayHubContract).not.toHaveProperty('revokeMachineCredential');
+    });
+    (0, bun_test_1.it)('leaves the deployed pod and session routers under /v2', () => {
+        (0, bun_test_1.expect)(relay_pods_contract_1.relayPodsContract.me.path).toBe('/v2/relay-pods/me');
+        (0, bun_test_1.expect)(relay_pod_sessions_contract_1.relayPodSessionsContract.exchange.path).toBe('/v2/relay-pod-sessions/exchange');
+    });
+});