@sudobility/screenwriter_types 0.1.1

package/dist/sharing/index.d.ts

@@ -0,0 +1,256 @@
+/**
+ * Tenancy management and sharing DTOs (spec 05 §5.3, §5.4, §6.2-6.4, §6.7, §6.21, §8.3), slice B8.
+ */
+import { z } from 'zod';
+import { type Role } from '../tenancy/index.js';
+export declare const TEAM_WORKSPACE_LIMIT = 50;
+export declare const workspaceCreateSchema: z.ZodObject<{
+    name: z.ZodString;
+    avatarAssetId: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+}, z.core.$strip>;
+export type WorkspaceCreateRequest = z.infer<typeof workspaceCreateSchema>;
+export declare const workspaceUpdateSchema: z.ZodObject<{
+    name: z.ZodOptional<z.ZodString>;
+    avatarAssetId: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    defaultTemplateId: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    defaultLanguage: z.ZodOptional<z.ZodString>;
+    aiEnabled: z.ZodOptional<z.ZodBoolean>;
+    allowPublicLinks: z.ZodOptional<z.ZodBoolean>;
+}, z.core.$strip>;
+export type WorkspaceUpdateRequest = z.infer<typeof workspaceUpdateSchema>;
+export declare const workspaceDeleteSchema: z.ZodObject<{
+    confirmName: z.ZodString;
+}, z.core.$strip>;
+export type WorkspaceDeleteRequest = z.infer<typeof workspaceDeleteSchema>;
+/** `DELETE /workspaces/:wid` response (soft delete). */
+export interface WorkspaceDeleteResponse {
+    deletedAt: string;
+}
+export declare const workspaceTransferSchema: z.ZodObject<{
+    toUserId: z.ZodString;
+}, z.core.$strip>;
+export type WorkspaceTransferRequest = z.infer<typeof workspaceTransferSchema>;
+/** `GET /workspaces/:wid/audit.csv` query: an ISO-8601 range of at most one year. */
+export declare const workspaceAuditQuerySchema: z.ZodObject<{
+    from: z.ZodOptional<z.ZodISODateTime>;
+    to: z.ZodOptional<z.ZodISODateTime>;
+}, z.core.$strip>;
+export type WorkspaceAuditQuery = z.infer<typeof workspaceAuditQuerySchema>;
+export declare const AUDIT_CSV_COLUMNS: readonly ["created_at", "actor", "action", "target_type", "target_id", "ip"];
+export declare const AUDIT_MAX_RANGE_DAYS = 366;
+export interface WorkspaceUsage {
+    storageBytes: number;
+    quotaBytes: number;
+    documentCount: number;
+    assetCount: number;
+}
+export interface Member {
+    userId: string;
+    email: string | null;
+    displayName: string | null;
+    role: Role;
+    invitedBy: string | null;
+    joinedAt: string;
+}
+export declare const memberUpdateSchema: z.ZodObject<{
+    role: z.ZodEnum<{
+        owner: "owner";
+        admin: "admin";
+        writer: "writer";
+        commenter: "commenter";
+        viewer: "viewer";
+    }>;
+}, z.core.$strip>;
+export type MemberUpdateRequest = z.infer<typeof memberUpdateSchema>;
+export declare const INVITATION_TARGETS: readonly ["workspace", "project", "document"];
+export type InvitationTarget = (typeof INVITATION_TARGETS)[number];
+export declare const INVITATION_TTL_DAYS = 14;
+export declare const INVITATION_STATUSES: readonly ["pending", "accepted", "declined", "cancelled", "expired"];
+export type InvitationStatus = (typeof INVITATION_STATUSES)[number];
+/** `role` for a workspace invitation is `admin|writer|commenter|viewer` (never `owner`); for a project or document it is a grant role. */
+export declare const invitationCreateSchema: z.ZodObject<{
+    email: z.ZodEmail;
+    role: z.ZodEnum<{
+        owner: "owner";
+        admin: "admin";
+        writer: "writer";
+        commenter: "commenter";
+        viewer: "viewer";
+    }>;
+}, z.core.$strip>;
+export type InvitationCreateRequest = z.infer<typeof invitationCreateSchema>;
+/** The token is never in this shape: it travels only in the invitation email (`notifyInvitation`, slice B12). */
+export interface Invitation {
+    id: string;
+    targetType: InvitationTarget;
+    workspaceId: string;
+    projectId: string | null;
+    documentId: string | null;
+    email: string;
+    role: Role;
+    invitedBy: string;
+    /** Inviter's display name or email, and the target's name, so an invitee can recognise it. */
+    invitedByName: string | null;
+    targetName: string | null;
+    status: InvitationStatus;
+    expiresAt: string;
+    createdAt: string;
+}
+export declare const invitationAcceptSchema: z.ZodObject<{
+    token: z.ZodString;
+}, z.core.$strip>;
+export type InvitationAcceptRequest = z.infer<typeof invitationAcceptSchema>;
+export interface InvitationAcceptResult {
+    workspaceId?: string;
+    projectId?: string;
+    documentId?: string;
+}
+/** Where an invitation, grant list or link list points. */
+export type ShareTarget = {
+    type: 'workspace';
+    id: string;
+} | {
+    type: 'project';
+    id: string;
+} | {
+    type: 'document';
+    id: string;
+};
+export interface ShareGrant {
+    id: string;
+    targetType: 'project' | 'document';
+    projectId: string | null;
+    documentId: string | null;
+    userId: string;
+    email: string | null;
+    displayName: string | null;
+    role: Role;
+    grantedBy: string | null;
+    createdAt: string;
+    updatedAt: string;
+}
+export declare const grantUpdateSchema: z.ZodObject<{
+    role: z.ZodEnum<{
+        owner: "owner";
+        admin: "admin";
+        writer: "writer";
+        commenter: "commenter";
+        viewer: "viewer";
+    }>;
+}, z.core.$strip>;
+export type GrantUpdateRequest = z.infer<typeof grantUpdateSchema>;
+/** `GET /me/shared` item: a project or document reached through a grant, not through a workspace membership. */
+export interface SharedItem {
+    type: 'project' | 'document';
+    id: string;
+    title: string;
+    role: Role;
+    workspaceId: string;
+    /** For a document: its project. */
+    projectId: string | null;
+    projectName: string | null;
+    sharedBy: string | null;
+    grantedAt: string;
+}
+export declare const SHARE_LINK_ACCESS: readonly ["view", "comment"];
+export type ShareLinkAccess = (typeof SHARE_LINK_ACCESS)[number];
+/** `anyone`: the URL alone opens it at `access`. `restricted`: only people on the access list (grants/membership). */
+export declare const SHARE_LINK_GENERAL_ACCESS: readonly ["anyone", "restricted"];
+export type ShareLinkGeneralAccess = (typeof SHARE_LINK_GENERAL_ACCESS)[number];
+export declare const SHARE_LINK_TARGETS: readonly ["project", "document", "snapshot"];
+export type ShareLinkTarget = (typeof SHARE_LINK_TARGETS)[number];
+export declare const SHARE_LINK_TOKEN_PREFIX = "fws_";
+/** Link session (`fls_...`) lifetime, seconds (spec 05 §5.4). */
+export declare const LINK_SESSION_TTL_S = 900;
+export declare const LINK_SESSION_PREFIX = "fls_";
+export declare const shareLinkCreateSchema: z.ZodObject<{
+    access: z.ZodEnum<{
+        view: "view";
+        comment: "comment";
+    }>;
+    generalAccess: z.ZodDefault<z.ZodEnum<{
+        anyone: "anyone";
+        restricted: "restricted";
+    }>>;
+    expiresAt: z.ZodOptional<z.ZodNullable<z.ZodISODateTime>>;
+    password: z.ZodOptional<z.ZodString>;
+    allowDownload: z.ZodDefault<z.ZodBoolean>;
+    watermarkText: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+}, z.core.$strip>;
+export type ShareLinkCreateRequest = z.input<typeof shareLinkCreateSchema>;
+export declare const shareLinkUpdateSchema: z.ZodObject<{
+    access: z.ZodOptional<z.ZodEnum<{
+        view: "view";
+        comment: "comment";
+    }>>;
+    generalAccess: z.ZodOptional<z.ZodEnum<{
+        anyone: "anyone";
+        restricted: "restricted";
+    }>>;
+    expiresAt: z.ZodOptional<z.ZodNullable<z.ZodISODateTime>>;
+    password: z.ZodOptional<z.ZodString>;
+    clearPassword: z.ZodOptional<z.ZodBoolean>;
+    allowDownload: z.ZodOptional<z.ZodBoolean>;
+    watermarkText: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+}, z.core.$strip>;
+export type ShareLinkUpdateRequest = z.infer<typeof shareLinkUpdateSchema>;
+export interface ShareLink {
+    id: string;
+    targetType: ShareLinkTarget;
+    projectId: string | null;
+    documentId: string | null;
+    snapshotId: string | null;
+    access: ShareLinkAccess;
+    generalAccess: ShareLinkGeneralAccess;
+    /** Last 4 characters of the token, for the UI list. */
+    tokenHint: string;
+    hasPassword: boolean;
+    allowDownload: boolean;
+    watermarkText: string | null;
+    expiresAt: string | null;
+    revokedAt: string | null;
+    accessCount: number;
+    lastAccessedAt: string | null;
+    createdBy: string | null;
+    createdAt: string;
+}
+/** The full token (and so the URL) is returned once, at creation. */
+export type ShareLinkCreated = ShareLink & {
+    url: string;
+    token: string;
+};
+export interface ShareLinkRevokeResponse {
+    revokedAt: string;
+}
+/** `GET /public/share/:token` (no content, no auth). A restricted link hides the title. */
+export interface PublicShareInfo {
+    targetType: ShareLinkTarget;
+    title: string | null;
+    access: ShareLinkAccess;
+    generalAccess: ShareLinkGeneralAccess;
+    requiresPassword: boolean;
+    /** True for a `comment` link: adding a note needs a signed-in user. */
+    requiresSignInToComment: boolean;
+    expiresAt: string | null;
+    allowDownload: boolean;
+}
+export declare const shareUnlockSchema: z.ZodObject<{
+    password: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+export type ShareUnlockRequest = z.infer<typeof shareUnlockSchema>;
+/** Also the way to obtain (and renew) a session for a password-less link. Send `linkSession` as `Authorization: Bearer` on `/share/:token/*` and as the sync `link` auth token. */
+export interface ShareUnlockResponse {
+    linkSession: string;
+    expiresAt: string;
+    /** What the session allows: `comment` only for a comment link opened by a signed-in user. */
+    access: ShareLinkAccess;
+}
+export declare const UNLOCK_SESSION_TTL_S = 1800;
+export declare const REAUTH_MAX_AGE_S = 300;
+export interface DocumentLockResponse {
+    locked: boolean;
+}
+export interface UnlockSession {
+    sessionToken: string;
+    expiresAt: string;
+}

package/dist/sharing/index.js

@@ -0,0 +1,91 @@
+/**
+ * Tenancy management and sharing DTOs (spec 05 §5.3, §5.4, §6.2-6.4, §6.7, §6.21, §8.3), slice B8.
+ */
+import { z } from 'zod';
+import { roleSchema } from '../tenancy/index.js';
+// ─── Workspaces ─────────────────────────────────────────────────────────────
+export const TEAM_WORKSPACE_LIMIT = 50;
+export const workspaceCreateSchema = z.object({
+    name: z.string().trim().min(1).max(80),
+    avatarAssetId: z.string().min(1).nullable().optional(),
+});
+export const workspaceUpdateSchema = z.object({
+    name: z.string().trim().min(1).max(80).optional(),
+    avatarAssetId: z.string().min(1).nullable().optional(),
+    defaultTemplateId: z.string().min(1).nullable().optional(),
+    defaultLanguage: z.string().min(2).max(35).optional(),
+    aiEnabled: z.boolean().optional(),
+    allowPublicLinks: z.boolean().optional(),
+});
+export const workspaceDeleteSchema = z.object({ confirmName: z.string() });
+export const workspaceTransferSchema = z.object({
+    toUserId: z.string().min(1),
+});
+/** `GET /workspaces/:wid/audit.csv` query: an ISO-8601 range of at most one year. */
+export const workspaceAuditQuerySchema = z.object({
+    from: z.iso.datetime({ offset: true }).optional(),
+    to: z.iso.datetime({ offset: true }).optional(),
+});
+export const AUDIT_CSV_COLUMNS = [
+    'created_at',
+    'actor',
+    'action',
+    'target_type',
+    'target_id',
+    'ip',
+];
+export const AUDIT_MAX_RANGE_DAYS = 366;
+export const memberUpdateSchema = z.object({ role: roleSchema });
+// ─── Invitations ────────────────────────────────────────────────────────────
+export const INVITATION_TARGETS = ['workspace', 'project', 'document'];
+export const INVITATION_TTL_DAYS = 14;
+export const INVITATION_STATUSES = [
+    'pending',
+    'accepted',
+    'declined',
+    'cancelled',
+    'expired',
+];
+/** `role` for a workspace invitation is `admin|writer|commenter|viewer` (never `owner`); for a project or document it is a grant role. */
+export const invitationCreateSchema = z.object({
+    email: z.email().max(254),
+    role: roleSchema,
+});
+export const invitationAcceptSchema = z.object({ token: z.string().min(1) });
+export const grantUpdateSchema = z.object({ role: roleSchema });
+// ─── Share links ────────────────────────────────────────────────────────────
+export const SHARE_LINK_ACCESS = ['view', 'comment'];
+/** `anyone`: the URL alone opens it at `access`. `restricted`: only people on the access list (grants/membership). */
+export const SHARE_LINK_GENERAL_ACCESS = ['anyone', 'restricted'];
+export const SHARE_LINK_TARGETS = ['project', 'document', 'snapshot'];
+export const SHARE_LINK_TOKEN_PREFIX = 'fws_';
+/** Link session (`fls_...`) lifetime, seconds (spec 05 §5.4). */
+export const LINK_SESSION_TTL_S = 900;
+export const LINK_SESSION_PREFIX = 'fls_';
+export const shareLinkCreateSchema = z.object({
+    access: z.enum(SHARE_LINK_ACCESS),
+    generalAccess: z.enum(SHARE_LINK_GENERAL_ACCESS).default('anyone'),
+    expiresAt: z.iso.datetime({ offset: true }).nullable().optional(),
+    password: z.string().min(1).max(200).optional(),
+    allowDownload: z.boolean().default(true),
+    watermarkText: z.string().max(200).nullable().optional(),
+});
+export const shareLinkUpdateSchema = z
+    .object({
+    access: z.enum(SHARE_LINK_ACCESS).optional(),
+    generalAccess: z.enum(SHARE_LINK_GENERAL_ACCESS).optional(),
+    expiresAt: z.iso.datetime({ offset: true }).nullable().optional(),
+    password: z.string().min(1).max(200).optional(),
+    clearPassword: z.boolean().optional(),
+    allowDownload: z.boolean().optional(),
+    watermarkText: z.string().max(200).nullable().optional(),
+})
+    .refine((v) => !(v.password !== undefined && v.clearPassword), {
+    message: 'password and clearPassword are exclusive',
+});
+export const shareUnlockSchema = z.object({
+    password: z.string().max(200).optional(),
+});
+// ─── Document lock ──────────────────────────────────────────────────────────
+export const UNLOCK_SESSION_TTL_S = 1800;
+export const REAUTH_MAX_AGE_S = 300;

package/dist/sync/codec.d.ts

@@ -0,0 +1,7 @@
+import { type SyncFrame } from './index.js';
+export declare class SyncCodecError extends Error {
+    constructor(message: string);
+}
+export declare function encodeFrame(frame: SyncFrame): Uint8Array;
+/** Throws `SyncCodecError` on any malformed or schema-invalid frame. */
+export declare function decodeFrame(bytes: Uint8Array): SyncFrame;

package/dist/sync/codec.js

@@ -0,0 +1,91 @@
+/**
+ * Binary wire codec for sync frames (spec 03 §2.2). Shared by the API and the frontend client.
+ * Platform-free: only `lib0` (pure JS), no Node built-ins, no DOM.
+ *
+ *   frame := channelId:varuint  messageType:varuint  payload
+ *
+ * Payload by type:
+ *  - JSON UTF-8 (the JSON text fills the rest of the frame): auth, authOk, authError, reauth, ping/pong, subscribe, subscribed, subscribeError,
+ *    unsubscribe, ack, reject, epochChanged, roleChanged, documentDeleted, normalized,
+ *    serverShutdown.
+ *  - syncStep1 / syncStep2 / awareness: `varuint8array` (the y-protocols payload, which is
+ *    exactly what follows the message-type tag in y-protocols/sync and /awareness).
+ *  - update: `epoch:varuint clientSeq:varuint update:varuint8array`.
+ *
+ * ping and pong share code 4. `decodeFrame` returns type `ping` for it; a heartbeat frame is a
+ * liveness signal only and must never be answered (otherwise the two sides would echo forever).
+ */
+import * as decoding from 'lib0/decoding';
+import * as encoding from 'lib0/encoding';
+import * as string from 'lib0/string';
+import { SYNC_MESSAGE_TYPES, syncFrameSchema, } from './index.js';
+export class SyncCodecError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = 'SyncCodecError';
+    }
+}
+const BINARY_TYPES = new Set(['syncStep1', 'syncStep2', 'awareness']);
+const NAME_BY_CODE = new Map();
+for (const [name, code] of Object.entries(SYNC_MESSAGE_TYPES)) {
+    // ping and pong share a code: the first registration (ping) wins on decode.
+    if (!NAME_BY_CODE.has(code))
+        NAME_BY_CODE.set(code, name);
+}
+export function encodeFrame(frame) {
+    const enc = encoding.createEncoder();
+    encoding.writeVarUint(enc, frame.channelId);
+    encoding.writeVarUint(enc, SYNC_MESSAGE_TYPES[frame.type]);
+    if (BINARY_TYPES.has(frame.type)) {
+        encoding.writeVarUint8Array(enc, frame.payload);
+    }
+    else if (frame.type === 'update') {
+        encoding.writeVarUint(enc, frame.payload.epoch);
+        encoding.writeVarUint(enc, frame.payload.clientSeq);
+        encoding.writeVarUint8Array(enc, frame.payload.update);
+    }
+    else {
+        encoding.writeUint8Array(enc, string.encodeUtf8(JSON.stringify(frame.payload)));
+    }
+    return encoding.toUint8Array(enc);
+}
+/** Throws `SyncCodecError` on any malformed or schema-invalid frame. */
+export function decodeFrame(bytes) {
+    let candidate;
+    try {
+        const dec = decoding.createDecoder(bytes);
+        const channelId = decoding.readVarUint(dec);
+        const code = decoding.readVarUint(dec);
+        const type = NAME_BY_CODE.get(code);
+        if (!type)
+            throw new SyncCodecError(`unknown message type ${code}`);
+        let payload;
+        if (BINARY_TYPES.has(type)) {
+            payload = decoding.readVarUint8Array(dec);
+            if (decoding.hasContent(dec))
+                throw new SyncCodecError('trailing bytes');
+        }
+        else if (type === 'update') {
+            const epoch = decoding.readVarUint(dec);
+            const clientSeq = decoding.readVarUint(dec);
+            const update = decoding.readVarUint8Array(dec);
+            if (decoding.hasContent(dec))
+                throw new SyncCodecError('trailing bytes');
+            payload = { epoch, clientSeq, update };
+        }
+        else {
+            const rest = decoding.readTailAsUint8Array(dec);
+            payload = JSON.parse(string.decodeUtf8(rest));
+        }
+        candidate = { channelId, type, payload };
+    }
+    catch (e) {
+        if (e instanceof SyncCodecError)
+            throw e;
+        throw new SyncCodecError(`malformed frame: ${e instanceof Error ? e.message : String(e)}`);
+    }
+    const parsed = syncFrameSchema.safeParse(candidate);
+    if (!parsed.success)
+        throw new SyncCodecError(`invalid frame: ${parsed.error.message}`);
+    return parsed.data;
+}