@shipfox/api-runners-dto 10.0.0 → 10.2.0

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@shipfox/api-runners-dto",
   "license": "MIT",
-  "version": "10.0.0",
+  "version": "10.2.0",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/ShipfoxHQ/shipfox.git",
@@ -23,8 +23,8 @@
   },
   "dependencies": {
     "zod": "^4.4.3",
-    "@shipfox/inter-module": "0.2.2",
-    "@shipfox/runner-labels": "0.1.3"
+    "@shipfox/runner-labels": "0.1.3",
+    "@shipfox/inter-module": "0.2.2"
   },
   "imports": {
     "#*": "./dist/*"

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,9 +86,14 @@ 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,
@@ -91,8 +112,16 @@ export {
   reportRunnerInstancesBodySchema,
   reportRunnerInstancesResponseSchema,
   reservationGrantSchema,
+  revokeAdministratorProvisionerTokenBodySchema,
+  revokeAdministratorProvisionerTokenResponseSchema,
   revokeManualRegistrationTokenResponseSchema,
   revokeProvisionerTokenResponseSchema,
+  runnerAdministratorAssignmentPresenceSchema,
+  runnerAdministratorEnrollmentStateSchema,
+  runnerAdministratorInstanceSchema,
+  runnerAdministratorLifecycleStateSchema,
+  runnerAdministratorReconciliationStatusSchema,
+  runnerAssignmentPollQuerySchema,
   runnerAssignmentPollResponseSchema,
   runnerBootstrapExchangeBodySchema,
   runnerBootstrapExchangeResponseSchema,

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,10 +138,13 @@ 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,

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';
@@ -33,7 +34,7 @@ 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),
@@ -46,6 +47,10 @@ 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(),
 });
@@ -58,3 +63,4 @@ export type RunnerBootstrapExchangeResponseDto = z.infer<
 >;
 export type RunnerEnrollmentBodyDto = z.infer<typeof runnerEnrollmentBodySchema>;
 export type RunnerEnrollmentResponseDto = z.infer<typeof runnerEnrollmentResponseSchema>;
+export type RunnerAssignmentPollQueryDto = z.infer<typeof runnerAssignmentPollQuerySchema>;