@sudobility/screenwriter_types 0.1.1

package/dist/templates/index.js

@@ -0,0 +1,70 @@
+import { z } from 'zod';
+/** `GET /templates` query: user templates always; `workspaceId` adds that workspace's; `scope` narrows. */
+export const templateListQuerySchema = z.object({
+    category: z.string().optional(),
+    workspaceId: z.string().optional(),
+    scope: z.enum(['builtin', 'user', 'workspace']).optional(),
+});
+/** `GET /templates/:tid?version=`: an older version of a user/workspace template (immutable). */
+export const templateGetQuerySchema = z.object({
+    version: z.coerce.number().int().min(1).optional(),
+});
+// ─── B14: template lifecycle (spec 05 §6.8) ─────────────────────────────────
+/** The body is validated server-side with writing_core's `TemplateJSON` schema (`TEMPLATE_INVALID` with the issues). */
+const templateBody = z.custom((v) => typeof v === 'object' && v !== null && !Array.isArray(v), {
+    message: 'template must be an object',
+});
+export const templateCreateSchema = z
+    .object({
+    scope: z.enum(['user', 'workspace']),
+    workspaceId: z.string().min(1).optional(),
+    template: templateBody,
+})
+    .refine((v) => v.scope !== 'workspace' || !!v.workspaceId, {
+    message: 'workspaceId is required for a workspace template',
+    path: ['workspaceId'],
+});
+export const templateVersionCreateSchema = z.object({ template: templateBody });
+export const templateUpdateSchema = z.object({
+    name: z.string().trim().min(1).max(120).optional(),
+    description: z.string().max(2000).nullable().optional(),
+    category: z.string().min(1).max(40).optional(),
+});
+/** Template file formats: Fadewright's own JSON and the two foreign ones spec 04 §4.3 names. */
+export const TEMPLATE_FILE_FORMATS = [
+    'fwtemplate',
+    'fadein-template',
+    'fdxt',
+];
+/** `{ "format": "fadewright-template", "formatVersion": 1, "template": <TemplateJSON> }` (spec 04 §4.3.1). */
+export const FWTEMPLATE_FORMAT = 'fadewright-template';
+export const FWTEMPLATE_FORMAT_VERSION = 1;
+/**
+ * `POST /templates/import`. Spec 05's `importId` flow is `templateImportByIdSchema` (B16); this body form (the file inline, like
+ * `documents/import`) keeps working. The result is the created template.
+ */
+export const templateImportSchema = z
+    .object({
+    scope: z.enum(['user', 'workspace']),
+    workspaceId: z.string().min(1).optional(),
+    filename: z.string().min(1).max(255),
+    contentB64: z.string().min(1),
+})
+    .refine((v) => v.scope !== 'workspace' || !!v.workspaceId, {
+    message: 'workspaceId is required for a workspace template',
+    path: ['workspaceId'],
+});
+/**
+ * The upload flow (B16): `POST /imports {templateTarget, filename, sizeBytes, sha256Hex}`, PUT the file, then
+ * `POST /templates/import {importId}`. Scope and workspace come from the upload, never from this request.
+ */
+export const templateImportByIdSchema = z.object({
+    importId: z.string().min(1),
+});
+/** `GET /templates/:tid/export?format=` (only `fwtemplate` is built). */
+export const templateExportQuerySchema = z.object({
+    format: z
+        .enum(['fwtemplate', 'json', 'fadein-template', 'fdxt'])
+        .default('fwtemplate'),
+    version: z.coerce.number().int().min(1).optional(),
+});

package/dist/tenancy/index.d.ts

@@ -0,0 +1,116 @@
+import { z } from 'zod';
+export declare const WORKSPACE_KINDS: readonly ["personal", "team"];
+export type WorkspaceKind = (typeof WORKSPACE_KINDS)[number];
+/** Ordered by authority (spec 05 §5.2). */
+export declare const ROLES: readonly ["owner", "admin", "writer", "commenter", "viewer"];
+export type Role = (typeof ROLES)[number];
+export declare const workspaceKindSchema: z.ZodEnum<{
+    personal: "personal";
+    team: "team";
+}>;
+export declare const roleSchema: z.ZodEnum<{
+    owner: "owner";
+    admin: "admin";
+    writer: "writer";
+    commenter: "commenter";
+    viewer: "viewer";
+}>;
+export interface WorkspaceSummary {
+    id: string;
+    kind: WorkspaceKind;
+    name: string;
+    avatarAssetId: string | null;
+}
+export interface Workspace extends WorkspaceSummary {
+    defaultTemplateId: string | null;
+    defaultLanguage: string;
+    aiEnabled: boolean;
+    /** F-SET-009: false disables every existing `anyone with the link` share link of the workspace and refuses new ones. */
+    allowPublicLinks: boolean;
+    createdAt: string;
+    updatedAt: string;
+}
+/** `GET /workspaces` item: summary plus the caller's role. */
+export type WorkspaceListItem = WorkspaceSummary & {
+    role: Role;
+};
+/** `GET /workspaces/:wid` */
+export type WorkspaceDetail = Workspace & {
+    role: Role;
+    memberCount: number;
+    storageBytes: number;
+};
+/**
+ * Every permission with the LOWEST role that holds it. The matrix is monotonic (a higher role has
+ * everything a lower one has), so `ROLE_PERMISSIONS` is derived from this table.
+ * Notes on the two permissions with a condition beyond the role:
+ *  - `share.manage` for a writer only applies to documents/projects they created (checked by the API).
+ *  - `project.trash` / `project.restore` for a writer only applies to projects they created.
+ */
+export declare const PERMISSION_MIN_ROLE: {
+    readonly 'workspace.read': "viewer";
+    readonly 'workspace.update': "admin";
+    readonly 'workspace.aiToggle': "owner";
+    readonly 'workspace.audit': "admin";
+    readonly 'workspace.delete': "owner";
+    readonly 'workspace.transfer': "owner";
+    readonly 'workspace.leave': "viewer";
+    readonly 'members.read': "viewer";
+    readonly 'members.invite': "admin";
+    readonly 'members.updateRole': "admin";
+    readonly 'members.remove': "admin";
+    readonly 'project.create': "writer";
+    readonly 'project.read': "viewer";
+    readonly 'project.update': "writer";
+    readonly 'project.trash': "writer";
+    readonly 'project.restore': "writer";
+    readonly 'project.purge': "admin";
+    readonly 'document.create': "writer";
+    readonly 'document.read': "viewer";
+    readonly 'document.export': "viewer";
+    readonly 'document.edit': "writer";
+    readonly 'document.comment': "commenter";
+    readonly 'document.chat': "commenter";
+    readonly 'document.activity': "viewer";
+    readonly 'document.trash': "writer";
+    readonly 'document.restore': "writer";
+    readonly 'document.move': "writer";
+    readonly 'document.lock': "writer";
+    readonly 'document.aiExclude': "writer";
+    readonly 'snapshot.create': "writer";
+    readonly 'snapshot.open': "writer";
+    readonly 'snapshot.fork': "writer";
+    readonly 'snapshot.cherryPick': "writer";
+    readonly 'snapshot.appendNote': "writer";
+    readonly 'snapshot.read': "viewer";
+    readonly 'snapshot.compare': "viewer";
+    readonly 'snapshot.hideForSelf': "viewer";
+    readonly 'version.restore': "writer";
+    readonly 'version.restoreAsCopy': "writer";
+    readonly 'share.manage': "writer";
+    readonly 'assets.upload': "writer";
+    readonly 'assets.link': "writer";
+    readonly 'assets.read': "viewer";
+    readonly 'ai.run': "writer";
+    readonly 'ai.review': "commenter";
+    readonly 'jobs.media': "writer";
+    readonly 'templates.manage': "writer";
+    readonly 'reports.run': "viewer";
+    readonly 'apiKeys.use': "viewer";
+};
+export type Permission = keyof typeof PERMISSION_MIN_ROLE;
+export declare const PERMISSIONS: Permission[];
+/** True when `a` has at least the authority of `b`. */
+export declare const roleAtLeast: (a: Role, b: Role) => boolean;
+/** The higher-authority of the given roles (nulls ignored); null when there are none. */
+export declare function maxRole(...roles: (Role | null | undefined)[]): Role | null;
+/** The lower-authority of two roles (used to cap an API key by its scope). */
+export declare const minRole: (a: Role, b: Role) => Role;
+export declare const ROLE_PERMISSIONS: Record<Role, readonly Permission[]>;
+/** The only check routes call. */
+export declare const hasPermission: (role: Role, permission: Permission) => boolean;
+/** Lowest role that holds `permission` (goes in a 403's `details.requiredRole`). */
+export declare const requiredRoleFor: (permission: Permission) => Role;
+/** Roles a share grant or a project/document invitation may carry: `owner` is never granted by share. */
+export declare const SHARE_ROLES: readonly ["admin", "writer", "commenter", "viewer"];
+export type ShareRole = (typeof SHARE_ROLES)[number];

package/dist/tenancy/index.js

@@ -0,0 +1,102 @@
+import { z } from 'zod';
+export const WORKSPACE_KINDS = ['personal', 'team'];
+/** Ordered by authority (spec 05 §5.2). */
+export const ROLES = [
+    'owner',
+    'admin',
+    'writer',
+    'commenter',
+    'viewer',
+];
+export const workspaceKindSchema = z.enum(WORKSPACE_KINDS);
+export const roleSchema = z.enum(ROLES);
+// ─── Permissions (spec 05 §5.2) ─────────────────────────────────────────────
+/**
+ * Every permission with the LOWEST role that holds it. The matrix is monotonic (a higher role has
+ * everything a lower one has), so `ROLE_PERMISSIONS` is derived from this table.
+ * Notes on the two permissions with a condition beyond the role:
+ *  - `share.manage` for a writer only applies to documents/projects they created (checked by the API).
+ *  - `project.trash` / `project.restore` for a writer only applies to projects they created.
+ */
+export const PERMISSION_MIN_ROLE = {
+    'workspace.read': 'viewer',
+    'workspace.update': 'admin',
+    'workspace.aiToggle': 'owner',
+    'workspace.audit': 'admin',
+    'workspace.delete': 'owner',
+    'workspace.transfer': 'owner',
+    'workspace.leave': 'viewer',
+    'members.read': 'viewer',
+    'members.invite': 'admin',
+    'members.updateRole': 'admin',
+    'members.remove': 'admin',
+    'project.create': 'writer',
+    'project.read': 'viewer',
+    'project.update': 'writer',
+    'project.trash': 'writer',
+    'project.restore': 'writer',
+    'project.purge': 'admin',
+    'document.create': 'writer',
+    'document.read': 'viewer',
+    'document.export': 'viewer',
+    'document.edit': 'writer',
+    'document.comment': 'commenter',
+    'document.chat': 'commenter',
+    'document.activity': 'viewer',
+    'document.trash': 'writer',
+    'document.restore': 'writer',
+    'document.move': 'writer',
+    'document.lock': 'writer',
+    'document.aiExclude': 'writer',
+    'snapshot.create': 'writer',
+    'snapshot.open': 'writer',
+    'snapshot.fork': 'writer',
+    'snapshot.cherryPick': 'writer',
+    'snapshot.appendNote': 'writer',
+    'snapshot.read': 'viewer',
+    'snapshot.compare': 'viewer',
+    'snapshot.hideForSelf': 'viewer',
+    'version.restore': 'writer',
+    'version.restoreAsCopy': 'writer',
+    'share.manage': 'writer',
+    'assets.upload': 'writer',
+    'assets.link': 'writer',
+    'assets.read': 'viewer',
+    'ai.run': 'writer',
+    'ai.review': 'commenter',
+    'jobs.media': 'writer',
+    'templates.manage': 'writer',
+    'reports.run': 'viewer',
+    'apiKeys.use': 'viewer',
+};
+export const PERMISSIONS = Object.keys(PERMISSION_MIN_ROLE);
+/** 0 = owner ... 4 = viewer; a smaller number is more authority. */
+const RANK = {
+    owner: 0,
+    admin: 1,
+    writer: 2,
+    commenter: 3,
+    viewer: 4,
+};
+/** True when `a` has at least the authority of `b`. */
+export const roleAtLeast = (a, b) => RANK[a] <= RANK[b];
+/** The higher-authority of the given roles (nulls ignored); null when there are none. */
+export function maxRole(...roles) {
+    let best = null;
+    for (const r of roles)
+        if (r && (best === null || RANK[r] < RANK[best]))
+            best = r;
+    return best;
+}
+/** The lower-authority of two roles (used to cap an API key by its scope). */
+export const minRole = (a, b) => (RANK[a] >= RANK[b] ? a : b);
+export const ROLE_PERMISSIONS = Object.fromEntries(ROLES.map((role) => [
+    role,
+    PERMISSIONS.filter((p) => roleAtLeast(role, PERMISSION_MIN_ROLE[p])),
+]));
+/** The only check routes call. */
+export const hasPermission = (role, permission) => roleAtLeast(role, PERMISSION_MIN_ROLE[permission]);
+/** Lowest role that holds `permission` (goes in a 403's `details.requiredRole`). */
+export const requiredRoleFor = (permission) => PERMISSION_MIN_ROLE[permission];
+/** Roles a share grant or a project/document invitation may carry: `owner` is never granted by share. */
+export const SHARE_ROLES = ['admin', 'writer', 'commenter', 'viewer'];

package/dist/test/index.d.ts

@@ -0,0 +1,8 @@
+/** Fixture factories for consumers' tests (`@sudobility/screenwriter_types/test`). */
+import type { Workspace } from '../tenancy/index.js';
+import type { Project, DocumentMeta } from '../projects/index.js';
+import type { SnapshotSummary } from '../versions/index.js';
+export declare function makeWorkspace(over?: Partial<Workspace>): Workspace;
+export declare function makeProject(over?: Partial<Project>): Project;
+export declare function makeDocumentMeta(over?: Partial<DocumentMeta>): DocumentMeta;
+export declare function makeSnapshotSummary(over?: Partial<SnapshotSummary>): SnapshotSummary;

package/dist/test/index.js

@@ -0,0 +1,88 @@
+const T = '2026-01-01T00:00:00.000Z';
+export function makeWorkspace(over = {}) {
+    return {
+        id: 'ws_test',
+        kind: 'personal',
+        name: 'Personal',
+        avatarAssetId: null,
+        defaultTemplateId: null,
+        defaultLanguage: 'en',
+        aiEnabled: true,
+        allowPublicLinks: true,
+        createdAt: T,
+        updatedAt: T,
+        ...over,
+    };
+}
+export function makeProject(over = {}) {
+    return {
+        id: 'prj_test',
+        workspaceId: 'ws_test',
+        name: 'Untitled Project',
+        description: null,
+        color: null,
+        coverAssetId: null,
+        kind: 'feature',
+        logline: null,
+        documentCount: 0,
+        createdAt: T,
+        updatedAt: T,
+        trashedAt: null,
+        role: 'owner',
+        folders: [],
+        documents: [],
+        ...over,
+    };
+}
+export function makeDocumentMeta(over = {}) {
+    return {
+        id: 'doc_test',
+        projectId: 'prj_test',
+        workspaceId: 'ws_test',
+        folderId: null,
+        kind: 'script',
+        title: 'Untitled Screenplay',
+        logline: null,
+        color: null,
+        labels: [],
+        season: null,
+        episode: null,
+        position: 0,
+        language: 'en',
+        templateId: null,
+        templateVersion: null,
+        epoch: 0,
+        excludeFromAi: false,
+        locked: false,
+        pageCount: 0,
+        sceneCount: 0,
+        wordCount: 0,
+        parentSnapshotId: null,
+        createdBy: null,
+        createdAt: T,
+        updatedAt: T,
+        lastEditedAt: null,
+        trashedAt: null,
+        ...over,
+    };
+}
+export function makeSnapshotSummary(over = {}) {
+    return {
+        id: 'snap_test',
+        documentId: 'doc_test',
+        parentId: null,
+        name: 'First draft',
+        note: null,
+        kind: 'manual',
+        autoReason: null,
+        stats: { pages: 0, scenes: 0, words: 0 },
+        createdBy: null,
+        createdOnDevice: null,
+        createdAt: T,
+        receivedAt: T,
+        forkedDocumentIds: [],
+        hiddenForMe: false,
+        noteCount: 0,
+        ...over,
+    };
+}