@sudobility/screenwriter_types 0.1.1

package/dist/collab/index.js

@@ -0,0 +1,211 @@
+/**
+ * Collaboration DTOs (spec 05 §6.15 notes/mentions/chat/activity, §6.16 notifications, §6.24 devices/push,
+ * §6.26 `writingReminder` prefs; slice B12). Tables: `note_mentions`, `document_chat_messages`, `activity_events`,
+ * `notifications`, `devices`.
+ */
+import { z } from 'zod';
+import { cursorQuerySchema } from '../api/pagination.js';
+// ─── Notification kinds and prefs (§6.16, §6.26) ────────────────────────────
+export const NOTIFICATION_KINDS = [
+    'mention',
+    'note_reply',
+    'note_on_my_document',
+    'snapshot_comment',
+    'chat_mention',
+    'invitation',
+    'share_granted',
+    'snapshot_opened_by_collaborator',
+    'job_finished',
+    'job_failed',
+    'ai_suggestions_ready',
+    'ai_refunded',
+    'export_ready',
+    'watermark_batch_sent',
+    'writing_reminder',
+    'credits_low',
+    'purchase_completed',
+    'account_deletion_scheduled',
+];
+export const NOTIFICATION_EMAIL_MODES = ['immediate', 'digest', 'off'];
+/** Kinds that default to an immediate email (the rest default to `digest` or `off`; see `defaultNotificationKindPrefs`). */
+const DEFAULT_IMMEDIATE_EMAIL = new Set([
+    'mention',
+    'note_reply',
+    'chat_mention',
+    'invitation',
+    'share_granted',
+    'job_failed',
+    'export_ready',
+    'watermark_batch_sent',
+    'credits_low',
+    'purchase_completed',
+    'account_deletion_scheduled',
+]);
+const DEFAULT_DIGEST_EMAIL = new Set([
+    'snapshot_comment',
+    'note_on_my_document',
+    'ai_suggestions_ready',
+    'ai_refunded',
+    'snapshot_opened_by_collaborator',
+]);
+/** Kinds a person is not plausibly interrupted for, off by default: no email, no push. */
+const DEFAULT_QUIET = new Set([
+    'job_finished',
+    'writing_reminder',
+]);
+/** Every kind gets a sane default; a person may override any of `inApp`/`push`/`email` per kind. */
+export function defaultNotificationKindPrefs(kind) {
+    const email = DEFAULT_IMMEDIATE_EMAIL.has(kind)
+        ? 'immediate'
+        : DEFAULT_DIGEST_EMAIL.has(kind)
+            ? 'digest'
+            : 'off';
+    return { inApp: true, push: !DEFAULT_QUIET.has(kind), email };
+}
+export function defaultNotificationPrefs() {
+    return {
+        kinds: Object.fromEntries(NOTIFICATION_KINDS.map((k) => [k, defaultNotificationKindPrefs(k)])),
+        writingReminderTime: null,
+    };
+}
+const notificationKindPrefsPatchSchema = z.object({
+    inApp: z.boolean().optional(),
+    push: z.boolean().optional(),
+    email: z.enum(NOTIFICATION_EMAIL_MODES).optional(),
+});
+const HHMM_RE = /^([01]\d|2[0-3]):[0-5]\d$/;
+/** `PUT /me/notification-prefs`: a sparse per-kind patch (only the kinds/fields given change) plus the reminder time. */
+export const notificationPrefsSchema = z.object({
+    kinds: z
+        .record(z.string(), notificationKindPrefsPatchSchema)
+        .refine((obj) => Object.keys(obj).every((k) => NOTIFICATION_KINDS.includes(k)), {
+        message: 'unknown notification kind',
+    })
+        .optional(),
+    writingReminderTime: z
+        .string()
+        .regex(HHMM_RE, 'writingReminderTime must be HH:MM (24h, local)')
+        .nullable()
+        .optional(),
+});
+/** `{...current, ...update}` per kind (a patch's fields win); `writingReminderTime` replaces whole. */
+export function mergeNotificationPrefs(current, update) {
+    const kinds = { ...current.kinds };
+    for (const [k, patch] of Object.entries(update.kinds ?? {})) {
+        const kind = k;
+        kinds[kind] = {
+            ...(kinds[kind] ?? defaultNotificationKindPrefs(kind)),
+            ...patch,
+        };
+    }
+    return {
+        kinds,
+        writingReminderTime: update.writingReminderTime === undefined
+            ? current.writingReminderTime
+            : update.writingReminderTime,
+    };
+}
+const boolQuery = z.enum(['true', 'false']).transform((v) => v === 'true');
+export const notificationsQuerySchema = cursorQuerySchema.extend({
+    unread: boolQuery.optional(),
+});
+export const notificationsReadSchema = z
+    .object({
+    ids: z.array(z.string().min(1)).max(200).optional(),
+    all: z.literal(true).optional(),
+    before: z.iso.datetime({ offset: true }).optional(),
+})
+    .refine((v) => v.ids !== undefined || v.all !== undefined || v.before !== undefined, {
+    message: 'one of ids, all or before is required',
+});
+// ─── Chat (§6.15, §8.7 `document_chat_messages`) ────────────────────────────
+export const CHAT_BODY_MAX = 4000;
+export const CHAT_EDIT_WINDOW_MINUTES = 15;
+/** Y.Doc notes use plain `mentions: string[]` (user ids, no offset/length: writing_core's simplification); chat mirrors it in the DTO for consistency with the spec's shape, offset/length optional. */
+export const mentionRefSchema = z.object({
+    userId: z.string().min(1),
+    offset: z.number().int().min(0).optional(),
+    length: z.number().int().min(1).optional(),
+});
+export const chatMessageCreateSchema = z.object({
+    clientMessageId: z
+        .string()
+        .min(8)
+        .max(64)
+        .regex(/^msg_[0-9A-Za-z]+$/, 'clientMessageId must be a msg_ prefixed id'),
+    body: z.string().trim().min(1).max(CHAT_BODY_MAX),
+    mentions: z.array(mentionRefSchema).max(50).optional(),
+});
+export const chatMessageUpdateSchema = z.object({
+    body: z.string().trim().min(1).max(CHAT_BODY_MAX),
+});
+export const chatQuerySchema = cursorQuerySchema.extend({
+    before: z.iso.datetime({ offset: true }).optional(),
+});
+// ─── Activity (§6.15, §8.7 `activity_events`) ───────────────────────────────
+export const ACTIVITY_KINDS = [
+    'document.created',
+    'document.renamed',
+    'document.moved',
+    'document.trashed',
+    'document.restored',
+    'session.edited',
+    'snapshot.created',
+    'snapshot.opened',
+    'snapshot.forked',
+    'version.restored',
+    'template.applied',
+    'import.over',
+    'revision.setCreated',
+    'locks.changed',
+    'changes.decided',
+    'ai.jobCompleted',
+    'ai.suggestionsDecided',
+    'share.granted',
+    'share.linkCreated',
+    'member.joined',
+    'member.left',
+    'mcp.commandsApplied',
+];
+export const ACTOR_KINDS = ['user', 'mcp', 'api', 'ai', 'system'];
+const csvList = (v) => typeof v === 'string'
+    ? v
+        .split(',')
+        .map((s) => s.trim())
+        .filter(Boolean)
+    : v;
+export const activityQuerySchema = cursorQuerySchema.extend({
+    kinds: z.preprocess(csvList, z.array(z.string())).optional(),
+});
+export const workspaceActivityQuerySchema = cursorQuerySchema.extend({
+    projectId: z.string().min(1).optional(),
+});
+// ─── Devices, push tokens (§6.24) ────────────────────────────────────────────
+export const DEVICE_PLATFORMS = [
+    'web',
+    'ios',
+    'ipados',
+    'android',
+    'macos',
+    'windows',
+];
+export const PUSH_PLATFORMS = ['apns', 'fcm', 'wns', 'webpush'];
+export const deviceCreateSchema = z.object({
+    id: z
+        .string()
+        .min(8)
+        .max(64)
+        .regex(/^dev_[0-9A-Za-z]+$/, 'id must be a dev_ prefixed id'),
+    installId: z.string().min(1).max(128),
+    displayName: z.string().trim().min(1).max(80),
+    platform: z.enum(DEVICE_PLATFORMS),
+    appVersion: z.string().min(1).max(40),
+});
+export const deviceUpdateSchema = z.object({
+    displayName: z.string().trim().min(1).max(80),
+});
+export const pushTokenSetSchema = z.object({
+    platform: z.enum(PUSH_PLATFORMS),
+    token: z.string().min(1).max(4096),
+    environment: z.enum(['production', 'sandbox']).optional(),
+});

package/dist/commands/index.d.ts

@@ -0,0 +1,92 @@
+import { z } from 'zod';
+/**
+ * A writing_core command as plain JSON. The command bodies are typed by
+ * writing_core; here they are opaque records until the API validates them.
+ */
+export type WritingCommandJson = Record<string, unknown>;
+export declare const COMMAND_BATCH_MAX = 500;
+export declare const commandBatchRequestSchema: z.ZodObject<{
+    commands: z.ZodArray<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+    baseEpoch: z.ZodNumber;
+    expectedHashes: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
+    dryRun: z.ZodOptional<z.ZodBoolean>;
+}, z.core.$strip>;
+export type CommandBatchRequest = z.infer<typeof commandBatchRequestSchema>;
+export interface CommandWarning {
+    index: number;
+    code: string;
+    message: string;
+}
+export interface CommandEffects {
+    /** Elements the batch created, changed and removed (sorted ids). */
+    createdIds: string[];
+    changedIds: string[];
+    deletedIds: string[];
+    /** Fresh content hashes (spec 11 4.2) of every created or changed element. */
+    newHashes: Record<string, string>;
+}
+/**
+ * `POST /documents/:did/commands` response (thin B5 version). A `dryRun` returns the same shape
+ * with `applied: 0` and `dryRun: true`: the effects the batch WOULD have, nothing changed.
+ * `expectedHashes` keys are element or scene ids; a mismatch is 409 `CONTENT_CHANGED` with
+ * `details.ids`.
+ */
+export interface CommandBatchResponse {
+    applied: number;
+    epoch: number;
+    dryRun?: boolean;
+    effects: CommandEffects;
+    warnings: CommandWarning[];
+}
+/** `COMMAND_INVALID` (422) `details`. `reason` is a writing_core ReasonCode (or `exception`). */
+export interface CommandInvalidDetails {
+    index: number;
+    reason: string;
+    detail?: Record<string, unknown>;
+}
+export declare const SCENE_BATCH_MAX = 20;
+export declare const ELEMENT_BATCH_MAX = 500;
+export interface OutlineScene {
+    id: string;
+    /** Formatted scene number label, or null when unnumbered. */
+    number: string | null;
+    heading: string;
+    omitted: boolean;
+    synopsis: string;
+    elementCount: number;
+    contentHash: string;
+}
+export interface OutlineResponse {
+    scenes: OutlineScene[];
+}
+export interface ElementRead {
+    id: string;
+    styleId: string;
+    styleName: string;
+    /** The style's role (`sceneHeading`, `action`, `character`, `dialogue`, ...), for callers that must not guess from names. */
+    styleRole?: string;
+    text: string;
+    contentHash: string;
+}
+export interface SceneRead {
+    id: string;
+    number: string | null;
+    heading: string;
+    synopsis: string;
+    contentHash: string;
+    elements: ElementRead[];
+}
+export declare const elementsBatchRequestSchema: z.ZodObject<{
+    elementIds: z.ZodArray<z.ZodString>;
+}, z.core.$strip>;
+export type ElementsBatchRequest = z.infer<typeof elementsBatchRequestSchema>;
+export interface ElementsBatchResponse {
+    elements: ElementRead[];
+}
+export declare const scenesBatchRequestSchema: z.ZodObject<{
+    sceneIds: z.ZodArray<z.ZodString>;
+}, z.core.$strip>;
+export type ScenesBatchRequest = z.infer<typeof scenesBatchRequestSchema>;
+export interface ScenesBatchResponse {
+    scenes: SceneRead[];
+}

package/dist/commands/index.js

@@ -0,0 +1,20 @@
+import { z } from 'zod';
+export const COMMAND_BATCH_MAX = 500;
+export const commandBatchRequestSchema = z.object({
+    commands: z
+        .array(z.record(z.string(), z.unknown()))
+        .min(1)
+        .max(COMMAND_BATCH_MAX),
+    baseEpoch: z.number().int().min(0),
+    expectedHashes: z.record(z.string(), z.string()).optional(),
+    dryRun: z.boolean().optional(),
+});
+// ---- Scene and element reads (spec 05 6.7.1, live document) ----
+export const SCENE_BATCH_MAX = 20;
+export const ELEMENT_BATCH_MAX = 500;
+export const elementsBatchRequestSchema = z.object({
+    elementIds: z.array(z.string().min(1)).min(1).max(ELEMENT_BATCH_MAX),
+});
+export const scenesBatchRequestSchema = z.object({
+    sceneIds: z.array(z.string().min(1)).min(1).max(SCENE_BATCH_MAX),
+});

package/dist/credits/index.d.ts

@@ -0,0 +1,26 @@
+import { z } from 'zod';
+/**
+ * Credits (spec 05 §6.20, spec 06 §10): a thin re-export of `@sudobility/types`' generic consumables
+ * shapes, plus the two things specific to Fadewright — the priced product catalog and the purchase
+ * handoff for platforms that cannot buy in-app (spec 05 §6.21).
+ *
+ * The ledger itself (`consumable_balances/_purchases/_usages`) is `@sudobility/consumables_service`'s,
+ * called in-process from `screenwriter_api` exactly as `music_api` does; this module never redefines it.
+ */
+export type { ConsumableBalanceResponse, ConsumablePurchaseRecord, ConsumablePurchaseRequest, ConsumableSource, ConsumableUsageRecord, ConsumableUseRequest, ConsumableUseResponse, } from '@sudobility/types';
+export declare const CONSUMABLE_SOURCES: readonly ["web", "apple", "google", "free"];
+/** `GET /consumables/products`: the priced catalog (`CREDIT_PRODUCTS`, spec 06 §10.1). */
+export interface CreditProduct {
+    productId: string;
+    credits: number;
+}
+/** `POST /purchases/handoff` (spec 05 §6.21): lets a platform with no in-app purchase (Windows) send the user to the web to buy. */
+export declare const purchaseHandoffRequestSchema: z.ZodObject<{
+    productId: z.ZodOptional<z.ZodString>;
+    returnTo: z.ZodString;
+}, z.core.$strip>;
+export type PurchaseHandoffRequest = z.infer<typeof purchaseHandoffRequestSchema>;
+export interface PurchaseHandoffResponse {
+    handoffUrl: string;
+    expiresAt: string;
+}

package/dist/credits/index.js

@@ -0,0 +1,7 @@
+import { z } from 'zod';
+export const CONSUMABLE_SOURCES = ['web', 'apple', 'google', 'free'];
+/** `POST /purchases/handoff` (spec 05 §6.21): lets a platform with no in-app purchase (Windows) send the user to the web to buy. */
+export const purchaseHandoffRequestSchema = z.object({
+    productId: z.string().optional(),
+    returnTo: z.string().min(1).max(2000),
+});

package/dist/formats/index.d.ts

@@ -0,0 +1,87 @@
+import { z } from 'zod';
+import type { DocumentMeta } from '../projects/index.js';
+/** Import and export over HTTP (synchronous; spec 05 §6.18 minus the job framework). */
+/** Formats the server can import: ids of `writing_formats`. */
+export declare const IMPORT_FORMAT_IDS: readonly ["fountain", "fdx", "fadein"];
+export declare const EXPORT_FORMAT_IDS: readonly ["fountain", "fdx", "json"];
+export type ExportFormatId = (typeof EXPORT_FORMAT_IDS)[number];
+/** Default `IMPORT_MAX_BYTES`: 100 MiB of decoded file bytes. */
+export declare const IMPORT_MAX_BYTES_DEFAULT: number;
+/** Mirror of `writing_formats` `Diagnostic` (this package cannot depend on it). */
+export interface ConversionDiagnostic {
+    code: string;
+    severity: 'info' | 'warn' | 'loss' | 'error';
+    message: string;
+    feature: string;
+    count: number;
+    locations?: {
+        elementIndex?: number;
+        sourceLine?: number;
+        sourcePath?: string;
+    }[];
+}
+/** Mirror of `writing_formats` `ConversionReport` (spec 04 §3.1). */
+export interface ConversionReport {
+    direction: 'import' | 'export';
+    format: string;
+    sourceVersion?: string;
+    diagnostics: ConversionDiagnostic[];
+    stats: {
+        elements: number;
+        scenes: number;
+        pages?: number;
+        durationMs: number;
+    };
+    confidence?: number;
+    summary: {
+        info: number;
+        warn: number;
+        loss: number;
+        error: number;
+    };
+}
+/** `POST /projects/:pid/documents/import` (idempotent on `id`, like document create). */
+export declare const documentImportSchema: z.ZodObject<{
+    id: z.ZodOptional<z.ZodString>;
+    filename: z.ZodString;
+    contentB64: z.ZodString;
+    title: z.ZodOptional<z.ZodString>;
+    kind: z.ZodOptional<z.ZodEnum<{
+        outline: "outline";
+        script: "script";
+        bible: "bible";
+        treatment: "treatment";
+        other: "other";
+    }>>;
+    templateId: z.ZodOptional<z.ZodString>;
+    language: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+export type DocumentImportRequest = z.infer<typeof documentImportSchema>;
+export interface DocumentImportResult {
+    document: DocumentMeta;
+    report: ConversionReport;
+    /** Detected source format id. */
+    format: string;
+}
+/** `POST /documents/:did/export` */
+export declare const documentExportSchema: z.ZodObject<{
+    format: z.ZodString;
+}, z.core.$strip>;
+export type DocumentExportRequest = {
+    format: ExportFormatId;
+};
+export interface DocumentExportResult {
+    filename: string;
+    mimeType: string;
+    contentB64: string;
+    report: ConversionReport;
+    format: ExportFormatId;
+}
+/** `GET /formats` */
+export interface FormatInfo {
+    id: string;
+    label: string;
+    extensions: string[];
+    canImport: boolean;
+    canExport: boolean;
+}

package/dist/formats/index.js

@@ -0,0 +1,26 @@
+import { z } from 'zod';
+import { documentKindSchema } from '../projects/index.js';
+/** Import and export over HTTP (synchronous; spec 05 §6.18 minus the job framework). */
+/** Formats the server can import: ids of `writing_formats`. */
+export const IMPORT_FORMAT_IDS = ['fountain', 'fdx', 'fadein'];
+export const EXPORT_FORMAT_IDS = ['fountain', 'fdx', 'json'];
+/** Default `IMPORT_MAX_BYTES`: 100 MiB of decoded file bytes. */
+export const IMPORT_MAX_BYTES_DEFAULT = 100 * 1024 * 1024;
+/** `POST /projects/:pid/documents/import` (idempotent on `id`, like document create). */
+export const documentImportSchema = z.object({
+    /** Client-generated `doc_...`; import is idempotent on it. */
+    id: z.string().startsWith('doc_').optional(),
+    /** Only a hint: the format is detected from the content. */
+    filename: z.string().min(1).max(500),
+    /** Base64 of the file bytes. */
+    contentB64: z.string(),
+    /** Defaults to the file's title page title, then the filename. */
+    title: z.string().trim().min(1).max(200).optional(),
+    kind: documentKindSchema.optional(),
+    templateId: z.string().optional(),
+    language: z.string().max(16).optional(),
+});
+/** `POST /documents/:did/export` */
+export const documentExportSchema = z.object({
+    format: z.string().min(1).max(32),
+});

package/dist/ids/index.d.ts

@@ -0,0 +1,2 @@
+export { ID_PREFIXES, newId, idKind, isId } from '@sudobility/writing_core';
+export type { IdPrefix, Id } from '@sudobility/writing_core';

package/dist/ids/index.js

@@ -0,0 +1,2 @@
+// Ids are owned by writing_core (R1); re-exported so consumers import from one place.
+export { ID_PREFIXES, newId, idKind, isId } from '@sudobility/writing_core';

package/dist/index.d.ts

@@ -0,0 +1,33 @@
+/**
+ * @sudobility/screenwriter_types
+ * Shared types and Zod schemas for the Fadewright frontend and backend.
+ * Import from the package root only.
+ */
+export * from './api/envelope.js';
+export * from './api/pagination.js';
+export * from './api/routes.js';
+export * from './ids/index.js';
+export * from './tenancy/index.js';
+export * from './sharing/index.js';
+export * from './projects/index.js';
+export * from './lifecycle/index.js';
+export * from './me/index.js';
+export * from './account/index.js';
+export * from './templates/index.js';
+export * from './versions/index.js';
+export * from './commands/index.js';
+export * from './formats/index.js';
+export * from './io/index.js';
+export * from './keys/index.js';
+export * from './ai/index.js';
+export * from './jobs/index.js';
+export * from './reads/index.js';
+export * from './reports/index.js';
+export * from './packets/index.js';
+export * from './assets/index.js';
+export * from './collab/index.js';
+export * from './credits/index.js';
+export * from './public/index.js';
+export * from './admin/index.js';
+export * from './sync/index.js';
+export * from './sync/codec.js';

package/dist/index.js

@@ -0,0 +1,33 @@
+/**
+ * @sudobility/screenwriter_types
+ * Shared types and Zod schemas for the Fadewright frontend and backend.
+ * Import from the package root only.
+ */
+export * from './api/envelope.js';
+export * from './api/pagination.js';
+export * from './api/routes.js';
+export * from './ids/index.js';
+export * from './tenancy/index.js';
+export * from './sharing/index.js';
+export * from './projects/index.js';
+export * from './lifecycle/index.js';
+export * from './me/index.js';
+export * from './account/index.js';
+export * from './templates/index.js';
+export * from './versions/index.js';
+export * from './commands/index.js';
+export * from './formats/index.js';
+export * from './io/index.js';
+export * from './keys/index.js';
+export * from './ai/index.js';
+export * from './jobs/index.js';
+export * from './reads/index.js';
+export * from './reports/index.js';
+export * from './packets/index.js';
+export * from './assets/index.js';
+export * from './collab/index.js';
+export * from './credits/index.js';
+export * from './public/index.js';
+export * from './admin/index.js';
+export * from './sync/index.js';
+export * from './sync/codec.js';