@shipfox/api-logs-dto 2.0.0

package/package.json

@@ -0,0 +1,55 @@
+{
+  "name": "@shipfox/api-logs-dto",
+  "license": "MIT",
+  "version": "2.0.0",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/ShipfoxHQ/shipfox.git",
+    "directory": "libs/api/logs-dto"
+  },
+  "private": false,
+  "type": "module",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "imports": {
+    "#test/*": "./test/*",
+    "#*": {
+      "workspace-source": "./src/*",
+      "development": "./src/*",
+      "default": "./dist/*"
+    }
+  },
+  "exports": {
+    ".": {
+      "development": {
+        "types": "./src/index.ts",
+        "default": "./src/index.ts"
+      },
+      "default": {
+        "types": "./dist/index.d.ts",
+        "default": "./dist/index.js"
+      }
+    }
+  },
+  "dependencies": {
+    "zod": "^4.4.3"
+  },
+  "devDependencies": {
+    "@shipfox/biome": "1.8.1",
+    "@shipfox/depcruise": "1.0.1",
+    "@shipfox/ts-config": "1.3.8",
+    "@shipfox/vitest": "1.2.2",
+    "@shipfox/typescript": "1.1.6",
+    "@shipfox/swc": "1.2.5"
+  },
+  "scripts": {
+    "build": "shipfox-swc",
+    "check": "shipfox-biome-check",
+    "check:fix": "shipfox-biome-check --write",
+    "depcruise": "shipfox-depcruise",
+    "test": "shipfox-vitest-run",
+    "test:watch": "shipfox-vitest-watch",
+    "type": "shipfox-tsc-check",
+    "type:emit": "shipfox-tsc-emit"
+  }
+}

package/src/events.ts

@@ -0,0 +1,22 @@
+import {z} from 'zod';
+
+const nonEmptyStringSchema = z.string().nonempty();
+
+export const LOG_STREAM_CLOSED = 'logs.stream.closed' as const;
+
+export const logStreamClosedEventSchema = z.object({
+  workspaceId: nonEmptyStringSchema,
+  jobId: nonEmptyStringSchema,
+  stepId: nonEmptyStringSchema,
+  attempt: z.number(),
+  streamId: nonEmptyStringSchema,
+});
+export type LogStreamClosedEvent = z.infer<typeof logStreamClosedEventSchema>;
+
+export interface LogsEventMap {
+  [LOG_STREAM_CLOSED]: LogStreamClosedEvent;
+}
+
+export const logsEventSchemas = {
+  [LOG_STREAM_CLOSED]: logStreamClosedEventSchema,
+} satisfies Record<keyof LogsEventMap, z.ZodType>;

package/src/index.ts

@@ -0,0 +1,46 @@
+export {
+  LOG_STREAM_CLOSED,
+  type LogStreamClosedEvent,
+  type LogsEventMap,
+  logStreamClosedEventSchema,
+  logsEventSchemas,
+} from './events.js';
+export {
+  type AppendLogsQueryDto,
+  type AppendLogsResponseDto,
+  appendLogsQuerySchema,
+  appendLogsResponseSchema,
+  type LogRecord,
+  logRecordSchema,
+  MAX_RECORD_DATA_BYTES,
+  MAX_RECORD_NAME_BYTES,
+  type OffsetGapResponseDto,
+  offsetGapResponseSchema,
+  parseLogRecordLine,
+  parseRawLogRecordLine,
+  type RawLogRecord,
+  type ReadLogsQueryDto,
+  type ReadLogsResponseDto,
+  rawLogRecordSchema,
+  readLogsQuerySchema,
+  readLogsResponseSchema,
+  SESSION_VIEW_VERSION,
+  type SessionViewDto,
+  type SessionViewLifecycleRow,
+  type SessionViewMessageRow,
+  type SessionViewRawRow,
+  type SessionViewRow,
+  type SessionViewRowMeta,
+  type SessionViewThinkingRow,
+  type SessionViewToolCallRow,
+  type SessionViewToolResultRow,
+  sessionViewLifecycleRowSchema,
+  sessionViewMessageRowSchema,
+  sessionViewRawRowSchema,
+  sessionViewRowMetaSchema,
+  sessionViewRowSchema,
+  sessionViewSchema,
+  sessionViewThinkingRowSchema,
+  sessionViewToolCallRowSchema,
+  sessionViewToolResultRowSchema,
+} from './schemas/index.js';

package/src/schemas/append.test.ts

@@ -0,0 +1,50 @@
+import {appendLogsQuerySchema, offsetGapResponseSchema} from './append.js';
+
+describe('appendLogsQuerySchema', () => {
+  it('coerces string query params to integers', () => {
+    const parsed = appendLogsQuerySchema.parse({attempt: '1', offset: '0'});
+
+    expect(parsed).toEqual({attempt: 1, offset: 0});
+  });
+
+  it('accepts offset 0', () => {
+    const parsed = appendLogsQuerySchema.parse({attempt: '2', offset: '0'});
+
+    expect(parsed.offset).toBe(0);
+  });
+
+  it('rejects attempt below 1', () => {
+    const parse = () => appendLogsQuerySchema.parse({attempt: '0', offset: '0'});
+
+    expect(parse).toThrow();
+  });
+
+  it('rejects a negative offset', () => {
+    const parse = () => appendLogsQuerySchema.parse({attempt: '1', offset: '-5'});
+
+    expect(parse).toThrow();
+  });
+
+  it('rejects a non-integer offset', () => {
+    const parse = () => appendLogsQuerySchema.parse({attempt: '1', offset: '1.5'});
+
+    expect(parse).toThrow();
+  });
+
+  it('rejects an attempt beyond the Postgres integer range', () => {
+    const parse = () => appendLogsQuerySchema.parse({attempt: '2147483648', offset: '0'});
+
+    expect(parse).toThrow();
+  });
+});
+
+describe('offsetGapResponseSchema', () => {
+  it('matches the ClientError wire shape', () => {
+    const parsed = offsetGapResponseSchema.parse({
+      code: 'offset-gap',
+      details: {committed_length: 42},
+    });
+
+    expect(parsed).toEqual({code: 'offset-gap', details: {committed_length: 42}});
+  });
+});

package/src/schemas/append.ts

@@ -0,0 +1,55 @@
+import {z} from 'zod';
+
+/**
+ * Append endpoint contract: `POST .../steps/:stepId/logs?attempt=N&offset=B`.
+ *
+ * The body is raw NDJSON bytes (whole records, newline-terminated), not a
+ * Zod-validated object — it is parsed line by line against the raw log record
+ * union (`rawLogRecordSchema`). `offset` is a position in the raw
+ * NDJSON spool stream; both `offset` and the returned `committed_length` are
+ * bounded far below 2^53 by the accrual budget, so JavaScript `number` is safe.
+ */
+export const appendLogsQuerySchema = z.object({
+  attempt: z.coerce
+    .number()
+    .int()
+    .min(1)
+    .max(2_147_483_647)
+    .describe('Attempt number of the step this chunk belongs to.'),
+  offset: z.coerce
+    .number()
+    .int()
+    .min(0)
+    .describe(
+      'Byte position of this chunk in the raw NDJSON spool. Must equal the server-held committed length: an earlier offset is acknowledged as already applied, a later offset returns 409 so the runner rewinds.',
+    ),
+});
+
+export type AppendLogsQueryDto = z.infer<typeof appendLogsQuerySchema>;
+
+export const appendLogsResponseSchema = z.object({
+  committed_length: z
+    .number()
+    .int()
+    .min(0)
+    .describe('New server-held byte position after this chunk was applied.'),
+  capped: z
+    .boolean()
+    .describe('When true, the per-job log budget is exhausted and further output is dropped.'),
+});
+
+export type AppendLogsResponseDto = z.infer<typeof appendLogsResponseSchema>;
+
+/** Body of the 409 returned on an offset gap, so the runner rewinds its spool cursor. */
+export const offsetGapResponseSchema = z.object({
+  code: z.literal('offset-gap'),
+  details: z.object({
+    committed_length: z
+      .number()
+      .int()
+      .min(0)
+      .describe('Current server-held committed length the runner should rewind to.'),
+  }),
+});
+
+export type OffsetGapResponseDto = z.infer<typeof offsetGapResponseSchema>;

package/src/schemas/index.ts

@@ -0,0 +1,45 @@
+export {
+  type AppendLogsQueryDto,
+  type AppendLogsResponseDto,
+  appendLogsQuerySchema,
+  appendLogsResponseSchema,
+  type OffsetGapResponseDto,
+  offsetGapResponseSchema,
+} from './append.js';
+export {
+  type ReadLogsQueryDto,
+  type ReadLogsResponseDto,
+  readLogsQuerySchema,
+  readLogsResponseSchema,
+} from './read.js';
+export {
+  type LogRecord,
+  logRecordSchema,
+  MAX_RECORD_DATA_BYTES,
+  MAX_RECORD_NAME_BYTES,
+  parseLogRecordLine,
+  parseRawLogRecordLine,
+  type RawLogRecord,
+  rawLogRecordSchema,
+} from './record.js';
+export {
+  SESSION_VIEW_VERSION,
+  type SessionViewDto,
+  type SessionViewLifecycleRow,
+  type SessionViewMessageRow,
+  type SessionViewRawRow,
+  type SessionViewRow,
+  type SessionViewRowMeta,
+  type SessionViewThinkingRow,
+  type SessionViewToolCallRow,
+  type SessionViewToolResultRow,
+  sessionViewLifecycleRowSchema,
+  sessionViewMessageRowSchema,
+  sessionViewRawRowSchema,
+  sessionViewRowMetaSchema,
+  sessionViewRowSchema,
+  sessionViewSchema,
+  sessionViewThinkingRowSchema,
+  sessionViewToolCallRowSchema,
+  sessionViewToolResultRowSchema,
+} from './session-view.js';

package/src/schemas/read.test.ts

@@ -0,0 +1,69 @@
+import {readLogsQuerySchema, readLogsResponseSchema} from './read.js';
+
+describe('readLogsQuerySchema', () => {
+  it('defaults the cursor to 0 when omitted', () => {
+    const parsed = readLogsQuerySchema.parse({});
+
+    expect(parsed.cursor).toBe(0);
+  });
+
+  it('coerces a string cursor to an integer', () => {
+    const parsed = readLogsQuerySchema.parse({cursor: '42'});
+
+    expect(parsed.cursor).toBe(42);
+  });
+
+  it('rejects a negative cursor', () => {
+    const parse = () => readLogsQuerySchema.parse({cursor: '-1'});
+
+    expect(parse).toThrow();
+  });
+});
+
+describe('readLogsResponseSchema', () => {
+  it('parses the inline variant', () => {
+    const parsed = readLogsResponseSchema.parse({
+      mode: 'inline',
+      ndjson: '{"v":1,"ts":1,"type":"output","stream":"stdout","data":"hi\\n"}\n',
+      next_cursor: 7,
+      has_more: true,
+      state: 'open',
+      truncated: false,
+    });
+
+    expect(parsed.mode).toBe('inline');
+  });
+
+  it('parses the presigned variant', () => {
+    const parsed = readLogsResponseSchema.parse({
+      mode: 'presigned',
+      url: 'https://storage.example/logs/object?sig=abc',
+      state: 'closed',
+      expires_at: new Date().toISOString(),
+      total_bytes: 1024,
+      truncated: true,
+    });
+
+    expect(parsed.mode).toBe('presigned');
+  });
+
+  it('rejects an unknown mode', () => {
+    const parse = () => readLogsResponseSchema.parse({mode: 'proxy'});
+
+    expect(parse).toThrow();
+  });
+
+  it('rejects a non-URL presigned url', () => {
+    const parse = () =>
+      readLogsResponseSchema.parse({
+        mode: 'presigned',
+        url: 'not a url',
+        state: 'closed',
+        expires_at: new Date().toISOString(),
+        total_bytes: 1,
+        truncated: false,
+      });
+
+    expect(parse).toThrow();
+  });
+});

package/src/schemas/read.ts

@@ -0,0 +1,84 @@
+import {z} from 'zod';
+
+/**
+ * Read endpoint contract: `GET .../steps/:stepId/attempts/:attempt/logs?cursor=N`.
+ *
+ * `cursor` is an opaque chunk-sequence position, not a byte offset. Server-injected
+ * control tombstones (`capped`, `runner_lost`) do not advance the runner byte axis, so
+ * the read walks chunks by insertion `seq` to keep every record in stream order. The
+ * same `seq` walk backs compaction, so the inline `ndjson` is byte-identical to the
+ * decompressed compacted object. Start at 0 and echo back `next_cursor` to page forward.
+ */
+export const readLogsQuerySchema = z.object({
+  cursor: z.coerce
+    .number()
+    .int()
+    .min(0)
+    .default(0)
+    .describe(
+      'Opaque chunk-sequence cursor. Start at 0; echo back the previous response next_cursor to page forward. Not a byte offset.',
+    ),
+});
+
+export type ReadLogsQueryDto = z.infer<typeof readLogsQuerySchema>;
+
+/**
+ * Inline shape: stored NDJSON bytes from `cursor`, parsed client-side with
+ * `parseLogRecordLine`. Served while the stream is open or closed but not yet compacted.
+ * The bytes carry every record of every type for the `(step, attempt)`; the client
+ * filters by record type for display.
+ */
+const readLogsInlineSchema = z.object({
+  mode: z.literal('inline'),
+  ndjson: z
+    .string()
+    .describe('Stored NDJSON: every record for this (step, attempt) from cursor, in stream order.'),
+  next_cursor: z
+    .number()
+    .int()
+    .min(0)
+    .describe('Cursor to pass on the next poll to fetch records after this page.'),
+  has_more: z
+    .boolean()
+    .describe(
+      'True when more buffered records remain past this page; re-poll immediately to drain before tailing at the refresh interval.',
+    ),
+  state: z
+    .enum(['open', 'closed'])
+    .describe('Stream lifecycle: open still accepts appends, closed is terminal.'),
+  truncated: z
+    .boolean()
+    .describe('True when the stream was force-closed because the runner stopped reporting.'),
+});
+
+/**
+ * Presigned shape: a short-lived GET URL to the compacted object, fetched directly by
+ * the browser (API egress bypassed). Served once the stream is compacted (`object_key`
+ * set). The object is the same NDJSON the inline shape streams, gzip-compressed.
+ */
+const readLogsPresignedSchema = z.object({
+  mode: z.literal('presigned'),
+  url: z.string().url().describe('Presigned GET URL for the compacted NDJSON object.'),
+  state: z
+    .literal('closed')
+    .describe('Compacted streams are closed before they are served by URL.'),
+  expires_at: z
+    .string()
+    .datetime({offset: true})
+    .describe('ISO 8601 instant after which the presigned URL stops working.'),
+  total_bytes: z
+    .number()
+    .int()
+    .min(0)
+    .describe('Committed append byte position for the attempt. This is the runner CAS axis.'),
+  truncated: z
+    .boolean()
+    .describe('True when the stream was force-closed because the runner stopped reporting.'),
+});
+
+export const readLogsResponseSchema = z.discriminatedUnion('mode', [
+  readLogsInlineSchema,
+  readLogsPresignedSchema,
+]);
+
+export type ReadLogsResponseDto = z.infer<typeof readLogsResponseSchema>;