@sudobility/screenwriter_types 0.1.1

package/dist/jobs/index.d.ts

@@ -0,0 +1,278 @@
+import { z } from 'zod';
+import type { AiTask } from '../ai/index.js';
+/**
+ * Generic jobs (spec 05 §6.19, §13; slice B9). A job is one row of `jobs`; `ai_jobs` rows are mirrored as `ai.*`
+ * jobs (decision D21a) so `/ai/jobs/:id` and `/jobs/:id` read the same job.
+ */
+export declare const JOB_STATUSES: readonly ["queued", "running", "succeeded", "failed", "cancelled"];
+export type JobStatus = (typeof JOB_STATUSES)[number];
+export declare const TERMINAL_JOB_STATUSES: readonly ["succeeded", "failed", "cancelled"];
+export declare const isTerminalJobStatus: (s: JobStatus) => boolean;
+export declare const JOB_LANES: readonly ["ai", "interactive", "bulk", "system", "provider"];
+export type JobLane = (typeof JOB_LANES)[number];
+/**
+ * Closed vocabulary of job kinds, `<family>.<variant>` (R10). Every kind has a `job_kind_config` row; a kind
+ * without a registered runner is seeded disabled and `POST /jobs` answers `JOB_KIND_DISABLED`. Extend by adding a
+ * member here and a row in `screenwriter_api/src/services/jobs/kinds.ts`. `test.*` kinds exist only to prove the
+ * framework and are enabled only under `AI_TEST_MODE=1`.
+ */
+export declare const JOB_KINDS: readonly ["ai.review", "ai.polish", "ai.describe", "export.pdf", "export.fdx", "export.fountain", "export.fadein", "export.fadewright", "export.json", "export.docx", "watermark.batch", "import.fdx", "import.fountain", "import.fadein", "import.pdf", "import.ocr", "import.celtx", "import.scrivener", "import.fdxt", "report.render", "doc.applyTemplate", "doc.importOver", "doc.snapshotOpen", "doc.versionRestore", "doc.compare", "doc.normalize", "doc.renormalize", "doc.compact", "snapshot.project", "project.duplicate", "asset.derive", "account.export", "system.emailSend", "system.emailDigest", "system.writingReminder", "system.pushSend", "system.purge", "system.retentionSweep", "template.thumbnail", "image.generate", "image.edit", "image.upscale", "image.turnaround", "video.generate", "video.extend", "video.upscale", "video.lipSync", "voice.tts", "voice.cloneProfile", "voice.change", "music.generate", "sfx.generate", "audio.isolate", "model3d.generate", "model3d.convert", "model3d.rig", "storyboard.generate", "animatic.assemble", "timeline.export", "test.echo", "test.flaky"];
+export type JobKind = (typeof JOB_KINDS)[number];
+export declare const jobKindSchema: z.ZodEnum<{
+    "ai.review": "ai.review";
+    "ai.polish": "ai.polish";
+    "ai.describe": "ai.describe";
+    "export.pdf": "export.pdf";
+    "export.fdx": "export.fdx";
+    "export.fountain": "export.fountain";
+    "export.fadein": "export.fadein";
+    "export.fadewright": "export.fadewright";
+    "export.json": "export.json";
+    "export.docx": "export.docx";
+    "watermark.batch": "watermark.batch";
+    "import.fdx": "import.fdx";
+    "import.fountain": "import.fountain";
+    "import.fadein": "import.fadein";
+    "import.pdf": "import.pdf";
+    "import.ocr": "import.ocr";
+    "import.celtx": "import.celtx";
+    "import.scrivener": "import.scrivener";
+    "import.fdxt": "import.fdxt";
+    "report.render": "report.render";
+    "doc.applyTemplate": "doc.applyTemplate";
+    "doc.importOver": "doc.importOver";
+    "doc.snapshotOpen": "doc.snapshotOpen";
+    "doc.versionRestore": "doc.versionRestore";
+    "doc.compare": "doc.compare";
+    "doc.normalize": "doc.normalize";
+    "doc.renormalize": "doc.renormalize";
+    "doc.compact": "doc.compact";
+    "snapshot.project": "snapshot.project";
+    "project.duplicate": "project.duplicate";
+    "asset.derive": "asset.derive";
+    "account.export": "account.export";
+    "system.emailSend": "system.emailSend";
+    "system.emailDigest": "system.emailDigest";
+    "system.writingReminder": "system.writingReminder";
+    "system.pushSend": "system.pushSend";
+    "system.purge": "system.purge";
+    "system.retentionSweep": "system.retentionSweep";
+    "template.thumbnail": "template.thumbnail";
+    "image.generate": "image.generate";
+    "image.edit": "image.edit";
+    "image.upscale": "image.upscale";
+    "image.turnaround": "image.turnaround";
+    "video.generate": "video.generate";
+    "video.extend": "video.extend";
+    "video.upscale": "video.upscale";
+    "video.lipSync": "video.lipSync";
+    "voice.tts": "voice.tts";
+    "voice.cloneProfile": "voice.cloneProfile";
+    "voice.change": "voice.change";
+    "music.generate": "music.generate";
+    "sfx.generate": "sfx.generate";
+    "audio.isolate": "audio.isolate";
+    "model3d.generate": "model3d.generate";
+    "model3d.convert": "model3d.convert";
+    "model3d.rig": "model3d.rig";
+    "storyboard.generate": "storyboard.generate";
+    "animatic.assemble": "animatic.assemble";
+    "timeline.export": "timeline.export";
+    "test.echo": "test.echo";
+    "test.flaky": "test.flaky";
+}>;
+/** The `ai.*` kind an `AiTask` mirrors as (its `subkind` is the task itself). */
+export declare function aiKindForTask(task: AiTask): JobKind;
+export declare const isAiKind: (kind: string) => boolean;
+export interface JobProgress {
+    /** 0..1 */
+    fraction: number;
+    stage: string | null;
+    /** An i18n key plus params, never prose (spec 05 §13.6). */
+    message: string | null;
+}
+export interface JobUsage {
+    promptTokens?: number;
+    completionTokens?: number;
+    model?: string | null;
+    pages?: number;
+}
+/** What `GET /jobs/:id` says about an output: no storage key, no URL (fetch those from `/jobs/:id/outputs`). */
+export interface JobOutputSummary {
+    name: string;
+    mimeType: string;
+    sizeBytes: number;
+    recipientId?: string;
+    assetId?: string;
+    documentId?: string;
+}
+/** `GET /jobs/:jobId` never carries `request` or `result` bodies (spec 05 §10 rule 5), only summaries. */
+export interface Job {
+    id: string;
+    kind: JobKind;
+    subkind: string | null;
+    status: JobStatus;
+    progress: JobProgress;
+    documentId: string | null;
+    /** Small scalar digest of the request (long strings dropped, arrays counted). */
+    requestSummary: Record<string, unknown>;
+    sources: JobSource[];
+    estimate?: JobEstimate;
+    quotedCredits?: number | null;
+    chargedCredits?: number | null;
+    refundedCredits?: number | null;
+    error?: string | null;
+    errorCode?: string | null;
+    usage?: JobUsage;
+    outputs?: JobOutputSummary[];
+    cancelRequested: boolean;
+    sourcesChangedDuringRun?: boolean | null;
+    attempt: number;
+    createdAt: string;
+    startedAt: string | null;
+    finishedAt: string | null;
+}
+export interface JobEstimate {
+    credits: number;
+    billable: boolean;
+}
+export declare const jobSourceSchema: z.ZodObject<{
+    documentId: z.ZodString;
+    snapshotId: z.ZodOptional<z.ZodString>;
+    targetKind: z.ZodString;
+    targetId: z.ZodString;
+}, z.core.$strip>;
+export type JobSource = z.infer<typeof jobSourceSchema> & {
+    sourceHash?: string;
+};
+/** `POST /jobs`. `idempotencyKey` (or the `Idempotency-Key` header) makes a retried create return the original job. */
+export declare const jobCreateSchema: z.ZodObject<{
+    kind: z.ZodEnum<{
+        "ai.review": "ai.review";
+        "ai.polish": "ai.polish";
+        "ai.describe": "ai.describe";
+        "export.pdf": "export.pdf";
+        "export.fdx": "export.fdx";
+        "export.fountain": "export.fountain";
+        "export.fadein": "export.fadein";
+        "export.fadewright": "export.fadewright";
+        "export.json": "export.json";
+        "export.docx": "export.docx";
+        "watermark.batch": "watermark.batch";
+        "import.fdx": "import.fdx";
+        "import.fountain": "import.fountain";
+        "import.fadein": "import.fadein";
+        "import.pdf": "import.pdf";
+        "import.ocr": "import.ocr";
+        "import.celtx": "import.celtx";
+        "import.scrivener": "import.scrivener";
+        "import.fdxt": "import.fdxt";
+        "report.render": "report.render";
+        "doc.applyTemplate": "doc.applyTemplate";
+        "doc.importOver": "doc.importOver";
+        "doc.snapshotOpen": "doc.snapshotOpen";
+        "doc.versionRestore": "doc.versionRestore";
+        "doc.compare": "doc.compare";
+        "doc.normalize": "doc.normalize";
+        "doc.renormalize": "doc.renormalize";
+        "doc.compact": "doc.compact";
+        "snapshot.project": "snapshot.project";
+        "project.duplicate": "project.duplicate";
+        "asset.derive": "asset.derive";
+        "account.export": "account.export";
+        "system.emailSend": "system.emailSend";
+        "system.emailDigest": "system.emailDigest";
+        "system.writingReminder": "system.writingReminder";
+        "system.pushSend": "system.pushSend";
+        "system.purge": "system.purge";
+        "system.retentionSweep": "system.retentionSweep";
+        "template.thumbnail": "template.thumbnail";
+        "image.generate": "image.generate";
+        "image.edit": "image.edit";
+        "image.upscale": "image.upscale";
+        "image.turnaround": "image.turnaround";
+        "video.generate": "video.generate";
+        "video.extend": "video.extend";
+        "video.upscale": "video.upscale";
+        "video.lipSync": "video.lipSync";
+        "voice.tts": "voice.tts";
+        "voice.cloneProfile": "voice.cloneProfile";
+        "voice.change": "voice.change";
+        "music.generate": "music.generate";
+        "sfx.generate": "sfx.generate";
+        "audio.isolate": "audio.isolate";
+        "model3d.generate": "model3d.generate";
+        "model3d.convert": "model3d.convert";
+        "model3d.rig": "model3d.rig";
+        "storyboard.generate": "storyboard.generate";
+        "animatic.assemble": "animatic.assemble";
+        "timeline.export": "timeline.export";
+        "test.echo": "test.echo";
+        "test.flaky": "test.flaky";
+    }>;
+    input: z.ZodDefault<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+    sources: z.ZodDefault<z.ZodArray<z.ZodObject<{
+        documentId: z.ZodString;
+        snapshotId: z.ZodOptional<z.ZodString>;
+        targetKind: z.ZodString;
+        targetId: z.ZodString;
+    }, z.core.$strip>>>;
+    idempotencyKey: z.ZodOptional<z.ZodString>;
+    maxCredits: z.ZodOptional<z.ZodNumber>;
+    dryRun: z.ZodOptional<z.ZodBoolean>;
+}, z.core.$strip>;
+export type JobCreateRequest = z.input<typeof jobCreateSchema>;
+/** `dryRun: true` answers this instead of a job. */
+export interface JobDryRunResponse {
+    estimate: JobEstimate;
+}
+/** `?kind=` is exact (`export.pdf`) or a family prefix ending in a dot (`ai.`). */
+export declare const jobListQuerySchema: z.ZodObject<{
+    limit: z.ZodDefault<z.ZodCoercedNumber<unknown>>;
+    cursor: z.ZodOptional<z.ZodString>;
+    documentId: z.ZodOptional<z.ZodString>;
+    kind: z.ZodOptional<z.ZodString>;
+    status: z.ZodOptional<z.ZodEnum<{
+        cancelled: "cancelled";
+        queued: "queued";
+        running: "running";
+        succeeded: "succeeded";
+        failed: "failed";
+    }>>;
+}, z.core.$strip>;
+export type JobListQuery = z.input<typeof jobListQuerySchema>;
+/** `GET /jobs/:jobId?wait=N` long-polls up to N seconds (max 120) until status or progress stage changes. */
+export declare const JOB_WAIT_MAX_S = 120;
+export declare const jobGetQuerySchema: z.ZodObject<{
+    wait: z.ZodOptional<z.ZodCoercedNumber<unknown>>;
+}, z.core.$strip>;
+export type JobGetQuery = z.input<typeof jobGetQuerySchema>;
+export interface JobOutput extends JobOutputSummary {
+    /** Signed download URL (or a `data:` URL for a small inline output). */
+    url: string;
+    expiresAt: string | null;
+}
+export interface JobOutputsResponse {
+    outputs: JobOutput[];
+}
+/** `GET /jobs/:jobId/recipients` item (batch watermark, B16). */
+export interface JobRecipient {
+    id: string;
+    name: string;
+    email: string | null;
+    company: string | null;
+    exportId: string;
+    emailedAt: string | null;
+    firstDownloadedAt: string | null;
+    downloadCount: number;
+}
+/** `POST /webhooks/jobs/:adapterId`: every verified delivery answers this. */
+export interface JobWebhookResponse {
+    ok: true;
+}
+/** Header carrying `sha256=<hex HMAC-SHA256(secret, raw body)>` on a provider webhook. */
+export declare const JOB_WEBHOOK_SIGNATURE_HEADER = "X-Webhook-Signature";
+/** The generic `Idempotency-Key` header (spec 05 §6.25). Values are 1-128 characters. */
+export declare const IDEMPOTENCY_HEADER = "Idempotency-Key";
+export declare const IDEMPOTENT_REPLAY_HEADER = "Idempotent-Replayed";
+export declare const idempotencyKeySchema: z.ZodString;

package/dist/jobs/index.js

@@ -0,0 +1,138 @@
+import { z } from 'zod';
+import { cursorQuerySchema } from '../api/pagination.js';
+/**
+ * Generic jobs (spec 05 §6.19, §13; slice B9). A job is one row of `jobs`; `ai_jobs` rows are mirrored as `ai.*`
+ * jobs (decision D21a) so `/ai/jobs/:id` and `/jobs/:id` read the same job.
+ */
+export const JOB_STATUSES = [
+    'queued',
+    'running',
+    'succeeded',
+    'failed',
+    'cancelled',
+];
+export const TERMINAL_JOB_STATUSES = [
+    'succeeded',
+    'failed',
+    'cancelled',
+];
+export const isTerminalJobStatus = (s) => TERMINAL_JOB_STATUSES.includes(s);
+export const JOB_LANES = [
+    'ai',
+    'interactive',
+    'bulk',
+    'system',
+    'provider',
+];
+/**
+ * Closed vocabulary of job kinds, `<family>.<variant>` (R10). Every kind has a `job_kind_config` row; a kind
+ * without a registered runner is seeded disabled and `POST /jobs` answers `JOB_KIND_DISABLED`. Extend by adding a
+ * member here and a row in `screenwriter_api/src/services/jobs/kinds.ts`. `test.*` kinds exist only to prove the
+ * framework and are enabled only under `AI_TEST_MODE=1`.
+ */
+export const JOB_KINDS = [
+    'ai.review',
+    'ai.polish',
+    'ai.describe',
+    'export.pdf',
+    'export.fdx',
+    'export.fountain',
+    'export.fadein',
+    'export.fadewright',
+    'export.json',
+    'export.docx',
+    'watermark.batch',
+    'import.fdx',
+    'import.fountain',
+    'import.fadein',
+    'import.pdf',
+    'import.ocr',
+    'import.celtx',
+    'import.scrivener',
+    'import.fdxt',
+    'report.render',
+    'doc.applyTemplate',
+    'doc.importOver',
+    'doc.snapshotOpen',
+    'doc.versionRestore',
+    'doc.compare',
+    'doc.normalize',
+    'doc.renormalize',
+    'doc.compact',
+    'snapshot.project',
+    'project.duplicate',
+    'asset.derive',
+    'account.export',
+    'system.emailSend',
+    'system.emailDigest',
+    'system.writingReminder',
+    'system.pushSend',
+    'system.purge',
+    'system.retentionSweep',
+    'template.thumbnail',
+    // reserved for media adapters (spec 11 §6.2): registered, seeded disabled
+    'image.generate',
+    'image.edit',
+    'image.upscale',
+    'image.turnaround',
+    'video.generate',
+    'video.extend',
+    'video.upscale',
+    'video.lipSync',
+    'voice.tts',
+    'voice.cloneProfile',
+    'voice.change',
+    'music.generate',
+    'sfx.generate',
+    'audio.isolate',
+    'model3d.generate',
+    'model3d.convert',
+    'model3d.rig',
+    'storyboard.generate',
+    'animatic.assemble',
+    'timeline.export',
+    // framework tests
+    'test.echo',
+    'test.flaky',
+];
+export const jobKindSchema = z.enum(JOB_KINDS);
+/** The `ai.*` kind an `AiTask` mirrors as (its `subkind` is the task itself). */
+export function aiKindForTask(task) {
+    return task.startsWith('polish') ? 'ai.polish' : 'ai.review';
+}
+export const isAiKind = (kind) => kind.startsWith('ai.');
+export const jobSourceSchema = z.object({
+    documentId: z.string().min(1),
+    snapshotId: z.string().min(1).optional(),
+    targetKind: z.string().min(1).max(40),
+    targetId: z.string().min(1).max(100),
+});
+/** `POST /jobs`. `idempotencyKey` (or the `Idempotency-Key` header) makes a retried create return the original job. */
+export const jobCreateSchema = z.object({
+    kind: jobKindSchema,
+    input: z.record(z.string(), z.unknown()).default({}),
+    sources: z.array(jobSourceSchema).max(20).default([]),
+    idempotencyKey: z.string().min(1).max(128).optional(),
+    maxCredits: z.number().int().min(0).optional(),
+    dryRun: z.boolean().optional(),
+});
+/** `?kind=` is exact (`export.pdf`) or a family prefix ending in a dot (`ai.`). */
+export const jobListQuerySchema = cursorQuerySchema.extend({
+    documentId: z.string().min(1).optional(),
+    kind: z
+        .string()
+        .regex(/^[A-Za-z0-9]+(\.[A-Za-z0-9]*)?$/)
+        .optional(),
+    status: z.enum(JOB_STATUSES).optional(),
+});
+/** `GET /jobs/:jobId?wait=N` long-polls up to N seconds (max 120) until status or progress stage changes. */
+export const JOB_WAIT_MAX_S = 120;
+export const jobGetQuerySchema = z.object({
+    wait: z.coerce.number().int().min(0).max(JOB_WAIT_MAX_S).optional(),
+});
+/** Header carrying `sha256=<hex HMAC-SHA256(secret, raw body)>` on a provider webhook. */
+export const JOB_WEBHOOK_SIGNATURE_HEADER = 'X-Webhook-Signature';
+/** The generic `Idempotency-Key` header (spec 05 §6.25). Values are 1-128 characters. */
+export const IDEMPOTENCY_HEADER = 'Idempotency-Key';
+export const IDEMPOTENT_REPLAY_HEADER = 'Idempotent-Replayed';
+export const idempotencyKeySchema = z.string().min(1).max(128);

package/dist/keys/index.d.ts

@@ -0,0 +1,53 @@
+import { z } from 'zod';
+/** Personal API keys (`fwk_`), spec 05 4.2 and 6.5. */
+export declare const API_KEY_SCOPES: readonly ["read", "read_write"];
+export type ApiKeyScope = (typeof API_KEY_SCOPES)[number];
+export declare const apiKeyScopeSchema: z.ZodEnum<{
+    read: "read";
+    read_write: "read_write";
+}>;
+/** At most this many active (unrevoked) keys per user. */
+export declare const API_KEY_MAX_ACTIVE = 25;
+/** `fwk_` + 8-char public prefix + `_` + 32 bytes base64url secret. */
+export declare const API_KEY_FORMAT_RE: RegExp;
+/** `GET /api-keys` item. Never contains the secret. */
+export interface ApiKeySummary {
+    id: string;
+    name: string;
+    /** The 8-char public prefix. */
+    prefix: string;
+    workspaceId: string;
+    scope: ApiKeyScope;
+    ai: boolean;
+    createdAt: string;
+    lastUsedAt: string | null;
+    expiresAt: string | null;
+    revokedAt: string | null;
+}
+export declare const apiKeyCreateSchema: z.ZodObject<{
+    name: z.ZodString;
+    workspaceId: z.ZodString;
+    scope: z.ZodEnum<{
+        read: "read";
+        read_write: "read_write";
+    }>;
+    ai: z.ZodDefault<z.ZodBoolean>;
+    expiresInDays: z.ZodOptional<z.ZodNumber>;
+}, z.core.$strip>;
+export type ApiKeyCreateRequest = z.input<typeof apiKeyCreateSchema>;
+/** `POST /api-keys` response: the only time `key` is ever returned. */
+export type ApiKeyCreated = ApiKeySummary & {
+    key: string;
+};
+export declare const apiKeyUpdateSchema: z.ZodObject<{
+    name: z.ZodOptional<z.ZodString>;
+    ai: z.ZodOptional<z.ZodBoolean>;
+}, z.core.$strip>;
+export type ApiKeyUpdateRequest = z.infer<typeof apiKeyUpdateSchema>;
+/** `DELETE /api-keys/:kid` response. */
+export interface ApiKeyRevokeResponse {
+    revokedAt: string;
+}
+/** Sent by API clients so command transactions record the right origin (`fadewright-mcp/<version>`). */
+export declare const CLIENT_HEADER = "X-Client";
+export declare const MCP_CLIENT_NAME = "fadewright-mcp";

package/dist/keys/index.js

@@ -0,0 +1,22 @@
+import { z } from 'zod';
+/** Personal API keys (`fwk_`), spec 05 4.2 and 6.5. */
+export const API_KEY_SCOPES = ['read', 'read_write'];
+export const apiKeyScopeSchema = z.enum(API_KEY_SCOPES);
+/** At most this many active (unrevoked) keys per user. */
+export const API_KEY_MAX_ACTIVE = 25;
+/** `fwk_` + 8-char public prefix + `_` + 32 bytes base64url secret. */
+export const API_KEY_FORMAT_RE = /^fwk_([a-z0-9]{8})_([A-Za-z0-9_-]{43})$/;
+export const apiKeyCreateSchema = z.object({
+    name: z.string().trim().min(1).max(60),
+    workspaceId: z.string().min(1),
+    scope: apiKeyScopeSchema,
+    ai: z.boolean().default(false),
+    expiresInDays: z.number().int().min(1).max(365).optional(),
+});
+export const apiKeyUpdateSchema = z.object({
+    name: z.string().trim().min(1).max(60).optional(),
+    ai: z.boolean().optional(),
+});
+/** Sent by API clients so command transactions record the right origin (`fadewright-mcp/<version>`). */
+export const CLIENT_HEADER = 'X-Client';
+export const MCP_CLIENT_NAME = 'fadewright-mcp';