@shipfox/api-runners-dto 9.0.2 → 10.2.0

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@shipfox/api-runners-dto",
   "license": "MIT",
-  "version": "9.0.2",
+  "version": "10.2.0",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/ShipfoxHQ/shipfox.git",

package/src/index.ts

@@ -3,16 +3,20 @@ export {
   type ActiveRunnerDto,
   type ActiveRunnerStateDto,
   type ActiveRunnersResponseDto,
+  type AdministratorProvisionerTokenDto,
   type AssignRunnerInstancesBodyDto,
   type AssignRunnerInstancesResponseDto,
   activeProvisionerDtoSchema,
   activeRunnerDtoSchema,
   activeRunnerStateSchema,
   activeRunnersResponseSchema,
+  administratorProvisionerTokenSchema,
   assignRunnerInstancesBodySchema,
   assignRunnerInstancesResponseSchema,
   attachRunnerControlProviderIdBodySchema,
   type ClaimedJobResponseDto,
+  type CreateAdministratorProvisionerTokenBodyDto,
+  type CreateAdministratorProvisionerTokenResponseDto,
   type CreateManualRegistrationTokenBodyDto,
   type CreateManualRegistrationTokenResponseDto,
   type CreateProvisionerTokenBodyDto,
@@ -20,6 +24,8 @@ export {
   type CreateRunnerInstancesBodyDto,
   type CreateRunnerInstancesResponseDto,
   claimedJobResponseSchema,
+  createAdministratorProvisionerTokenBodySchema,
+  createAdministratorProvisionerTokenResponseSchema,
   createManualRegistrationTokenBodySchema,
   createManualRegistrationTokenResponseSchema,
   createProvisionerTokenBodySchema,
@@ -32,12 +38,22 @@ export {
   type HeartbeatResponseDto,
   heartbeatBodySchema,
   heartbeatResponseSchema,
+  type InstallationProvisionerTokenStatus,
+  installationProvisionerTokenStatusSchema,
   type ListActiveProvisionersResponseDto,
+  type ListAdministratorProvisionerTokensQueryDto,
+  type ListAdministratorProvisionerTokensResponseDto,
   type ListManualRegistrationTokensResponseDto,
   type ListProvisionerTokensResponseDto,
+  type ListRunnerAdministratorInstancesQueryDto,
+  type ListRunnerAdministratorInstancesResponseDto,
   listActiveProvisionersResponseSchema,
+  listAdministratorProvisionerTokensQuerySchema,
+  listAdministratorProvisionerTokensResponseSchema,
   listManualRegistrationTokensResponseSchema,
   listProvisionerTokensResponseSchema,
+  listRunnerAdministratorInstancesQuerySchema,
+  listRunnerAdministratorInstancesResponseSchema,
   MAX_MANUAL_REGISTRATION_TOKEN_TTL_SECONDS,
   MAX_OBSERVED_PROVIDER_RUNNER_ID_LENGTH,
   MAX_PROVIDER_KIND_LENGTH,
@@ -70,12 +86,18 @@ export {
   type ReportRunnerInstancesBodyDto,
   type ReportRunnerInstancesResponseDto,
   type ReservationGrantDto,
+  type RevokeAdministratorProvisionerTokenBodyDto,
+  type RevokeAdministratorProvisionerTokenResponseDto,
   type RevokeManualRegistrationTokenResponseDto,
   type RevokeProvisionerTokenResponseDto,
+  RUNNER_ASSIGNMENT_POLL_DEFAULT_WAIT_SECONDS,
   RUNNER_SESSION_EXHAUSTED_CODE,
+  type RunnerAdministratorInstanceDto,
+  type RunnerAssignmentPollQueryDto,
   type RunnerBootstrapExchangeBodyDto,
   type RunnerBootstrapExchangeResponseDto,
   type RunnerEnrollmentBodyDto,
+  type RunnerEnrollmentResponseDto,
   type RunnerHarnessToolCapabilitiesDto,
   type RunnerInstanceReportEventDto,
   type RunnerInstanceStateDto,
@@ -90,13 +112,22 @@ export {
   reportRunnerInstancesBodySchema,
   reportRunnerInstancesResponseSchema,
   reservationGrantSchema,
+  revokeAdministratorProvisionerTokenBodySchema,
+  revokeAdministratorProvisionerTokenResponseSchema,
   revokeManualRegistrationTokenResponseSchema,
   revokeProvisionerTokenResponseSchema,
+  runnerAdministratorAssignmentPresenceSchema,
+  runnerAdministratorEnrollmentStateSchema,
+  runnerAdministratorInstanceSchema,
+  runnerAdministratorLifecycleStateSchema,
+  runnerAdministratorReconciliationStatusSchema,
+  runnerAssignmentPollQuerySchema,
   runnerAssignmentPollResponseSchema,
   runnerBootstrapExchangeBodySchema,
   runnerBootstrapExchangeResponseSchema,
   runnerControlHeartbeatResponseSchema,
   runnerEnrollmentBodySchema,
+  runnerEnrollmentResponseSchema,
   runnerHarnessToolCapabilitiesSchema,
   runnerToolCapabilitiesSchema,
 } from '#schemas/index.js';

package/src/inter-module.ts

@@ -45,6 +45,18 @@ export const runnersInterModuleContract = defineInterModuleContract({
         reportFresh: z.boolean(),
       }),
     },
+    getWorkspaceJobCounts: {
+      input: z.object({workspaceIds: z.array(idSchema).min(1).max(100)}),
+      output: z.object({
+        counts: z.array(
+          z.object({
+            workspaceId: idSchema,
+            queued: z.number().int().nonnegative(),
+            running: z.number().int().nonnegative(),
+          }),
+        ),
+      }),
+    },
   },
 });
 

package/src/schemas/admin-provisioner-token.ts

@@ -0,0 +1,94 @@
+import {z} from 'zod';
+import {MAX_PROVISIONER_TOKEN_TTL_SECONDS} from './provisioner-token.js';
+
+const timestampSchema = z.string().datetime();
+const CONTROL_OR_FORMAT_CHARACTER_RE = /[\p{Cc}\p{Cf}]/u;
+const reasonSchema = z
+  .string()
+  .min(1)
+  .max(512)
+  .refine((value) => value.trim().length > 0, {
+    message: 'must not be blank',
+  })
+  .refine((value) => !CONTROL_OR_FORMAT_CHARACTER_RE.test(value), {
+    message: 'must not contain control or format characters',
+  });
+
+export const installationProvisionerTokenStatusSchema = z.enum(['active', 'expired', 'revoked']);
+
+export type InstallationProvisionerTokenStatus = z.infer<
+  typeof installationProvisionerTokenStatusSchema
+>;
+
+export const administratorProvisionerTokenSchema = z.object({
+  id: z.string().uuid(),
+  scope: z.literal('installation'),
+  prefix: z.string().min(1),
+  name: z.string().nullable(),
+  status: installationProvisionerTokenStatusSchema,
+  created_by_user_id: z.string().uuid(),
+  revoked_by_user_id: z.string().uuid().nullable(),
+  expires_at: timestampSchema.nullable(),
+  revoked_at: timestampSchema.nullable(),
+  last_seen_at: timestampSchema.nullable(),
+  created_at: timestampSchema,
+  updated_at: timestampSchema,
+});
+
+export type AdministratorProvisionerTokenDto = z.infer<typeof administratorProvisionerTokenSchema>;
+
+export const createAdministratorProvisionerTokenBodySchema = z.object({
+  name: z.string().min(1).max(256).optional(),
+  ttl_seconds: z.number().int().positive().max(MAX_PROVISIONER_TOKEN_TTL_SECONDS).optional(),
+  reason: reasonSchema,
+});
+
+export type CreateAdministratorProvisionerTokenBodyDto = z.infer<
+  typeof createAdministratorProvisionerTokenBodySchema
+>;
+
+export const createAdministratorProvisionerTokenResponseSchema =
+  administratorProvisionerTokenSchema.extend({
+    raw_token: z.string().min(1),
+    correlation_id: z.string().min(1).max(255),
+  });
+
+export type CreateAdministratorProvisionerTokenResponseDto = z.infer<
+  typeof createAdministratorProvisionerTokenResponseSchema
+>;
+
+export const listAdministratorProvisionerTokensQuerySchema = z.object({
+  status: installationProvisionerTokenStatusSchema.optional(),
+  limit: z.coerce.number().int().min(1).max(100).default(50),
+  cursor: z.string().optional(),
+});
+
+export type ListAdministratorProvisionerTokensQueryDto = z.infer<
+  typeof listAdministratorProvisionerTokensQuerySchema
+>;
+
+export const listAdministratorProvisionerTokensResponseSchema = z.object({
+  tokens: z.array(administratorProvisionerTokenSchema),
+  next_cursor: z.string().nullable(),
+});
+
+export type ListAdministratorProvisionerTokensResponseDto = z.infer<
+  typeof listAdministratorProvisionerTokensResponseSchema
+>;
+
+export const revokeAdministratorProvisionerTokenBodySchema = z.object({
+  reason: reasonSchema,
+});
+
+export type RevokeAdministratorProvisionerTokenBodyDto = z.infer<
+  typeof revokeAdministratorProvisionerTokenBodySchema
+>;
+
+export const revokeAdministratorProvisionerTokenResponseSchema =
+  administratorProvisionerTokenSchema.extend({
+    correlation_id: z.string().min(1).max(255),
+  });
+
+export type RevokeAdministratorProvisionerTokenResponseDto = z.infer<
+  typeof revokeAdministratorProvisionerTokenResponseSchema
+>;

package/src/schemas/admin-runner-instances.ts

@@ -0,0 +1,76 @@
+import {MAX_RUNNER_LABELS} from '@shipfox/runner-labels';
+import {z} from 'zod';
+import {runnerLabelSchema} from './register.js';
+import {providerRunnerStateSchema} from './report-runner-instances.js';
+
+export const runnerAdministratorLifecycleStateSchema = z.enum([
+  'unassigned',
+  'assigned',
+  'activated',
+  'claimed',
+  'completed',
+]);
+
+export const runnerAdministratorEnrollmentStateSchema = z.enum([
+  'pending',
+  'enrolled',
+  'activated',
+]);
+
+export const runnerAdministratorAssignmentPresenceSchema = z.enum(['assigned', 'unassigned']);
+
+export const runnerAdministratorReconciliationStatusSchema = z.enum([
+  'current',
+  'stale',
+  'terminal',
+  'unknown',
+]);
+
+const runnerAdministratorAssignedWorkspaceSchema = z.object({
+  id: z.string().uuid(),
+});
+
+const runnerAdministratorProvisionerSchema = z.object({
+  id: z.string().uuid(),
+  scope: z.literal('installation'),
+  name: z.string().nullable(),
+});
+
+export const runnerAdministratorInstanceSchema = z.object({
+  id: z.string().uuid(),
+  lifecycle_state: runnerAdministratorLifecycleStateSchema,
+  compute_state: providerRunnerStateSchema,
+  enrollment_state: runnerAdministratorEnrollmentStateSchema,
+  assignment_presence: runnerAdministratorAssignmentPresenceSchema,
+  assigned_workspace: runnerAdministratorAssignedWorkspaceSchema.nullable(),
+  labels: z.array(runnerLabelSchema).max(MAX_RUNNER_LABELS),
+  created_at: z.string().datetime(),
+  last_heartbeat_at: z.string().datetime(),
+  closure_reason: z.string().max(500).nullable(),
+  closed_at: z.string().datetime().nullable(),
+  provisioner: runnerAdministratorProvisionerSchema,
+  reconciliation_status: runnerAdministratorReconciliationStatusSchema,
+});
+
+export type RunnerAdministratorInstanceDto = z.infer<typeof runnerAdministratorInstanceSchema>;
+
+export const listRunnerAdministratorInstancesQuerySchema = z.object({
+  state: providerRunnerStateSchema.optional(),
+  assignment: runnerAdministratorAssignmentPresenceSchema.optional(),
+  label: runnerLabelSchema.optional(),
+  limit: z.coerce.number().int().min(1).max(100).default(50),
+  cursor: z.string().optional(),
+});
+
+export type ListRunnerAdministratorInstancesQueryDto = z.infer<
+  typeof listRunnerAdministratorInstancesQuerySchema
+>;
+
+export const listRunnerAdministratorInstancesResponseSchema = z.object({
+  runners: z.array(runnerAdministratorInstanceSchema),
+  next_cursor: z.string().nullable(),
+});
+
+export type ListRunnerAdministratorInstancesResponseDto = z.infer<
+  typeof listRunnerAdministratorInstancesResponseSchema
+>;

package/src/schemas/index.ts

@@ -1,3 +1,33 @@
+export {
+  type AdministratorProvisionerTokenDto,
+  administratorProvisionerTokenSchema,
+  type CreateAdministratorProvisionerTokenBodyDto,
+  type CreateAdministratorProvisionerTokenResponseDto,
+  createAdministratorProvisionerTokenBodySchema,
+  createAdministratorProvisionerTokenResponseSchema,
+  type InstallationProvisionerTokenStatus,
+  installationProvisionerTokenStatusSchema,
+  type ListAdministratorProvisionerTokensQueryDto,
+  type ListAdministratorProvisionerTokensResponseDto,
+  listAdministratorProvisionerTokensQuerySchema,
+  listAdministratorProvisionerTokensResponseSchema,
+  type RevokeAdministratorProvisionerTokenBodyDto,
+  type RevokeAdministratorProvisionerTokenResponseDto,
+  revokeAdministratorProvisionerTokenBodySchema,
+  revokeAdministratorProvisionerTokenResponseSchema,
+} from './admin-provisioner-token.js';
+export {
+  type ListRunnerAdministratorInstancesQueryDto,
+  type ListRunnerAdministratorInstancesResponseDto,
+  listRunnerAdministratorInstancesQuerySchema,
+  listRunnerAdministratorInstancesResponseSchema,
+  type RunnerAdministratorInstanceDto,
+  runnerAdministratorAssignmentPresenceSchema,
+  runnerAdministratorEnrollmentStateSchema,
+  runnerAdministratorInstanceSchema,
+  runnerAdministratorLifecycleStateSchema,
+  runnerAdministratorReconciliationStatusSchema,
+} from './admin-runner-instances.js';
 export {
   type AssignRunnerInstancesBodyDto,
   type AssignRunnerInstancesResponseDto,
@@ -108,14 +138,19 @@ export {
   type CreateRunnerInstancesResponseDto,
   createRunnerInstancesBodySchema,
   createRunnerInstancesResponseSchema,
+  RUNNER_ASSIGNMENT_POLL_DEFAULT_WAIT_SECONDS,
+  type RunnerAssignmentPollQueryDto,
   type RunnerBootstrapExchangeBodyDto,
   type RunnerBootstrapExchangeResponseDto,
   type RunnerEnrollmentBodyDto,
+  type RunnerEnrollmentResponseDto,
+  runnerAssignmentPollQuerySchema,
   runnerAssignmentPollResponseSchema,
   runnerBootstrapExchangeBodySchema,
   runnerBootstrapExchangeResponseSchema,
   runnerControlHeartbeatResponseSchema,
   runnerEnrollmentBodySchema,
+  runnerEnrollmentResponseSchema,
 } from './runner-enrollment.js';
 export {
   type RunnerHarnessToolCapabilitiesDto,

package/src/schemas/poll-demand.test.ts

@@ -1,4 +1,32 @@
-import {pollDemandResponseSchema} from './poll-demand.js';
+import {pollDemandBodySchema, pollDemandResponseSchema} from './poll-demand.js';
+
+const pollDemandTemplate = {
+  template_key: 'linux',
+  labels: ['linux'],
+  available_slots: 1,
+  starting: 0,
+  running: 0,
+};
+
+describe('pollDemandBodySchema', () => {
+  it('accepts up to 1000 advertised templates', () => {
+    const result = pollDemandBodySchema.safeParse({
+      max_reservations: 0,
+      templates: Array.from({length: 1000}, () => pollDemandTemplate),
+    });
+
+    expect(result.success).toBe(true);
+  });
+
+  it('rejects more than 1000 advertised templates', () => {
+    const result = pollDemandBodySchema.safeParse({
+      max_reservations: 0,
+      templates: Array.from({length: 1001}, () => pollDemandTemplate),
+    });
+
+    expect(result.success).toBe(false);
+  });
+});
 
 describe('pollDemandResponseSchema', () => {
   it('requires datetime response fields to be ISO datetimes', () => {

package/src/schemas/poll-demand.ts

@@ -13,7 +13,7 @@ export const pollDemandTemplateSchema = z.object({
 export const pollDemandBodySchema = z.object({
   wait_seconds: z.number().int().min(0).optional(),
   max_reservations: z.number().int().min(0).max(1000),
-  templates: z.array(pollDemandTemplateSchema).max(100),
+  templates: z.array(pollDemandTemplateSchema).max(1000),
 });
 
 export const demandStatSchema = z.object({

package/src/schemas/report-runner-instances.test.ts

@@ -41,6 +41,24 @@ describe('providerRunnerReportEventSchema', () => {
 });
 
 describe('reportRunnerInstancesBodySchema', () => {
+  it('accepts a batch at the limit', () => {
+    const event = {
+      provider_runner_id: 'container-1',
+      labels: ['linux'],
+      state: 'running',
+      reported_at: new Date().toISOString(),
+    };
+
+    const result = reportRunnerInstancesBodySchema.safeParse({
+      events: Array.from({length: MAX_PROVIDER_RUNNER_REPORT_EVENTS}, (_, index) => ({
+        ...event,
+        provider_runner_id: `container-${index}`,
+      })),
+    });
+
+    expect(result.success).toBe(true);
+  });
+
   it('enforces the batch size limit', () => {
     const event = {
       provider_runner_id: 'container-1',

package/src/schemas/runner-enrollment.test.ts

@@ -0,0 +1,52 @@
+import {
+  RUNNER_ASSIGNMENT_POLL_DEFAULT_WAIT_SECONDS,
+  runnerAssignmentPollQuerySchema,
+  runnerEnrollmentBodySchema,
+} from './runner-enrollment.js';
+
+describe('runnerAssignmentPollQuerySchema', () => {
+  it('coerces a bounded wait from the HTTP query string', () => {
+    expect(runnerAssignmentPollQuerySchema.parse({wait_seconds: '12'})).toEqual({
+      wait_seconds: 12,
+    });
+  });
+
+  it('rejects a zero-second assignment wait', () => {
+    expect(runnerAssignmentPollQuerySchema.safeParse({wait_seconds: '0'}).success).toBe(false);
+  });
+
+  it.each(['-1', '1.5', 'not-a-number'])('rejects invalid wait_seconds %s', (waitSeconds) => {
+    expect(runnerAssignmentPollQuerySchema.safeParse({wait_seconds: waitSeconds}).success).toBe(
+      false,
+    );
+  });
+});
+
+it('keeps the protocol default explicit', () => {
+  expect(RUNNER_ASSIGNMENT_POLL_DEFAULT_WAIT_SECONDS).toBe(30);
+});
+
+const validEnrollment = {
+  capabilities: undefined,
+  labels: ['linux'],
+  provider_kind: 'docker',
+  protocol_version: '1',
+};
+
+test('accepts the shared maximum runner label count', () => {
+  const result = runnerEnrollmentBodySchema.safeParse({
+    ...validEnrollment,
+    labels: Array.from({length: 20}, (_, index) => `label-${index}`),
+  });
+
+  expect(result.success).toBe(true);
+});
+
+test('rejects runner enrollment above the shared maximum label count', () => {
+  const result = runnerEnrollmentBodySchema.safeParse({
+    ...validEnrollment,
+    labels: Array.from({length: 21}, (_, index) => `label-${index}`),
+  });
+
+  expect(result.success).toBe(false);
+});

package/src/schemas/runner-enrollment.ts

@@ -1,3 +1,4 @@
+import {MAX_RUNNER_LABELS} from '@shipfox/runner-labels';
 import {z} from 'zod';
 import {runnerLabelSchema} from './register.js';
 import {runnerToolCapabilitiesSchema} from './tool-capabilities.js';
@@ -9,7 +10,14 @@ export const createRunnerInstancesBodySchema = z
   .object({
     provider_kind: z.string().min(1).max(64).optional(),
     runner_instances: z
-      .array(z.object({template_key: z.string().min(1).max(255).optional()}).strict())
+      .array(
+        z
+          .object({
+            template_key: z.string().min(1).max(255).optional(),
+            reservation_id: z.string().uuid().optional(),
+          })
+          .strict(),
+      )
       .min(1)
       .max(500),
   })
@@ -26,16 +34,23 @@ export const runnerBootstrapExchangeResponseSchema = z.object({
 });
 export const runnerEnrollmentBodySchema = z
   .object({
-    labels: z.array(runnerLabelSchema).min(1).max(100),
+    labels: z.array(runnerLabelSchema).min(1).max(MAX_RUNNER_LABELS),
     capabilities: runnerToolCapabilitiesSchema.optional(),
     provider_kind: z.string().min(1).max(64),
     protocol_version: z.string().min(1).max(64),
   })
   .strict();
+export const runnerEnrollmentResponseSchema = z.object({
+  activation_token: z.string().min(1).nullable(),
+});
 export const attachRunnerControlProviderIdBodySchema = z
   .object({provider_runner_id: z.string().min(1).max(255)})
   .strict();
 export const runnerControlHeartbeatResponseSchema = z.object({ok: z.literal(true)});
+export const RUNNER_ASSIGNMENT_POLL_DEFAULT_WAIT_SECONDS = 30;
+export const runnerAssignmentPollQuerySchema = z
+  .object({wait_seconds: z.coerce.number().int().min(1).optional()})
+  .strict();
 export const runnerAssignmentPollResponseSchema = z.object({
   activation_token: z.string().min(1).nullable(),
 });
@@ -47,3 +62,5 @@ export type RunnerBootstrapExchangeResponseDto = z.infer<
   typeof runnerBootstrapExchangeResponseSchema
 >;
 export type RunnerEnrollmentBodyDto = z.infer<typeof runnerEnrollmentBodySchema>;
+export type RunnerEnrollmentResponseDto = z.infer<typeof runnerEnrollmentResponseSchema>;
+export type RunnerAssignmentPollQueryDto = z.infer<typeof runnerAssignmentPollQuerySchema>;