@openstory/cli 0.0.0-stage → 0.1.0

package/dist/login.js

@@ -0,0 +1,148 @@
+/**
+ * Signing in to OpenStory with the public API's device code, and the keys it
+ * leaves in ~/.openstory/credentials.json, one per origin.
+ */
+import { mkdir, readFile, rename, stat, writeFile } from 'node:fs/promises';
+import { join } from 'node:path';
+import { errorText, recordOf, stringOf } from './api.js';
+import { parseOrigin } from './context.js';
+const DIR = '.openstory';
+const KEY_FILE = 'credentials.json';
+/** Where stitch kept the keys before 0.5.0. */
+const OLD_KEY_FILE = 'stitch.json';
+const DEVICE_WAIT = '60s';
+export const login = {
+    usage: 'openstory login [--origin url]',
+    async run(args, context) {
+        const { origin, rest } = parseOrigin(args);
+        if (rest[0] !== undefined)
+            throw new Error(`Unknown argument: ${rest[0]}`);
+        await signIn({ ...context, origin });
+    },
+};
+/** Renames stitch's key file once; never over an existing credentials file. */
+export async function moveOldCredentials(home) {
+    const dir = join(home, DIR);
+    if (await exists(join(dir, KEY_FILE)))
+        return;
+    if (!(await exists(join(dir, OLD_KEY_FILE))))
+        return;
+    await rename(join(dir, OLD_KEY_FILE), join(dir, KEY_FILE));
+}
+/** The stored key, or a fresh device-code sign-in. */
+export async function openStoryApiKey(options) {
+    return (await storedKey(options.home, options.origin)) ?? signIn(options);
+}
+export async function storedKey(home, origin) {
+    return (await readKeyFile(home)).keys[origin] ?? null;
+}
+async function readKeyFile(home) {
+    let text;
+    try {
+        text = await readFile(join(home, DIR, KEY_FILE), 'utf8');
+    }
+    catch (error) {
+        // Only a missing file means "no keys yet". Anything else would be
+        // overwritten by the next sign-in, taking every other origin's key with it.
+        if (isMissingFile(error))
+            return { keys: {} };
+        throw new Error(`~/${DIR}/${KEY_FILE} is unreadable: ${error instanceof Error ? error.message : String(error)}`);
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(text);
+    }
+    catch {
+        throw new Error(`~/${DIR}/${KEY_FILE} is not JSON; fix or remove it`);
+    }
+    const keys = recordOf(recordOf(parsed).keys);
+    return {
+        keys: Object.fromEntries(Object.entries(keys).filter((entry) => typeof entry[1] === 'string')),
+    };
+}
+async function exists(file) {
+    try {
+        await stat(file);
+        return true;
+    }
+    catch (error) {
+        if (isMissingFile(error))
+            return false;
+        throw error;
+    }
+}
+export function isMissingFile(error) {
+    return (typeof error === 'object' &&
+        error !== null &&
+        'code' in error &&
+        error.code === 'ENOENT');
+}
+async function storeKey(home, origin, key) {
+    const file = await readKeyFile(home);
+    file.keys[origin] = key;
+    const dir = join(home, DIR);
+    await mkdir(dir, { recursive: true, mode: 0o700 });
+    await writeFile(join(dir, KEY_FILE), JSON.stringify(file, null, 2), {
+        mode: 0o600,
+    });
+}
+/**
+ * The sign-in page must be on the server we are talking to: the string goes
+ * to the OS launcher, so no other origin or scheme is passed through.
+ */
+function sameOriginUrl(value, origin) {
+    let url;
+    try {
+        url = new URL(value);
+    }
+    catch {
+        throw new Error('OpenStory answered with an unreadable sign-in page');
+    }
+    if (url.origin !== origin) {
+        throw new Error(`The sign-in page is not on ${origin}`);
+    }
+    return url.href;
+}
+const sleep = (seconds) => new Promise((r) => setTimeout(r, seconds * 1000));
+/** Device-code sign-in (RFC 8628 shape); stores and returns the API key. */
+export async function signIn(options) {
+    const { origin, fetch: fetchFn } = options;
+    const started = await fetchFn(new URL('/api/v1/device/code', origin), {
+        method: 'POST',
+    });
+    if (!started.ok) {
+        throw new Error(`OpenStory could not start a sign-in (${started.status}) ${await errorText(started)}`);
+    }
+    const answer = recordOf(await started.json());
+    const code = {
+        deviceCode: stringOf(answer.device_code, 'a device code'),
+        userCode: stringOf(answer.user_code, 'a user code'),
+        verifyUrl: sameOriginUrl(stringOf(answer.verification_url_complete, 'a sign-in page'), origin),
+        interval: typeof answer.interval === 'number' ? answer.interval : 5,
+    };
+    options.stderr.write(`Sign in to OpenStory: open ${code.verifyUrl} and enter ${code.userCode}\n`);
+    options.open(code.verifyUrl);
+    const poll = new URL('/api/v1/device/token', origin);
+    poll.searchParams.set('device_code', code.deviceCode);
+    poll.searchParams.set('wait', DEVICE_WAIT);
+    for (;;) {
+        const response = await fetchFn(poll);
+        if (response.ok) {
+            const key = stringOf(recordOf(await response.json()).api_key, 'a key');
+            await storeKey(options.home, origin, key);
+            options.stderr.write('Signed in.\n');
+            return key;
+        }
+        // OpenStory long-polls on `wait`, so a 428 comes back after a minute; a
+        // server that answers at once is paced by its interval, like a 429.
+        if (response.status === 428 || response.status === 429) {
+            await sleep(code.interval);
+            continue;
+        }
+        throw new Error(response.status === 403
+            ? 'The sign-in was denied'
+            : response.status === 410
+                ? 'The sign-in code expired. Run the command again'
+                : `Sign-in failed (${response.status}) ${await errorText(response)}`);
+    }
+}

package/dist/pull.d.ts

@@ -0,0 +1,11 @@
+/** `openstory pull`: download one sequence's files into a folder. */
+import type { Command } from './context.js';
+export type PullArgs = {
+    sequenceId: string;
+    origin: string;
+    dir: string;
+    history: boolean;
+    exports: boolean;
+};
+export declare function parsePull(args: string[], cwd: string): PullArgs;
+export declare const pull: Command;

package/dist/pull.js

@@ -0,0 +1,63 @@
+/** `openstory pull`: download one sequence's files into a folder. */
+import { join, resolve } from 'node:path';
+import { downloadSequenceAssets } from './assets.js';
+import { parseOrigin } from './context.js';
+import { openStoryApiKey, signIn } from './login.js';
+export function parsePull(args, cwd) {
+    const { origin, rest: argv } = parseOrigin(args);
+    let dir = null;
+    let history = false;
+    let exportsFlag = false;
+    const rest = [];
+    for (let i = 0; i < argv.length; i++) {
+        const arg = argv[i] ?? '';
+        if (arg === '--dir') {
+            const value = argv[i + 1];
+            if (value === undefined || value.startsWith('-')) {
+                throw new Error('--dir needs a directory');
+            }
+            dir = resolve(cwd, value);
+            i += 1;
+        }
+        else if (arg === '--history')
+            history = true;
+        else if (arg === '--exports')
+            exportsFlag = true;
+        else if (arg.startsWith('-'))
+            throw new Error(`Unknown argument: ${arg}`);
+        else
+            rest.push(arg);
+    }
+    const sequenceId = rest[0];
+    if (sequenceId === undefined) {
+        throw new Error('openstory pull needs a sequence id');
+    }
+    if (rest.length > 1)
+        throw new Error(`Unknown argument: ${rest[1]}`);
+    return {
+        sequenceId,
+        origin,
+        dir: dir ?? resolve(cwd, sequenceId),
+        history,
+        exports: exportsFlag,
+    };
+}
+export const pull = {
+    usage: 'openstory pull <sequenceId> [--history] [--exports] [--origin url] [--dir dir]',
+    async run(args, context) {
+        const request = parsePull(args, context.cwd);
+        const auth = { ...context, origin: request.origin };
+        const result = await downloadSequenceAssets({
+            sequenceId: request.sequenceId,
+            origin: request.origin,
+            cacheDir: join(context.home, '.openstory', 'assets'),
+            dest: request.dir,
+            history: request.history,
+            includeExports: request.exports,
+            fetch: context.fetch,
+            key: () => openStoryApiKey(auth),
+            refresh: () => signIn(auth),
+        });
+        context.stdout.write(`Saved ${result.saved} files. Skipped ${result.skipped} already there.${result.removed > 0 ? ` Removed ${result.removed} no longer listed.` : ''}\n`);
+    },
+};

package/dist/share.d.ts

@@ -0,0 +1,21 @@
+/**
+ * `openstory share`: upload a cut to OpenStory and get a link anyone can open.
+ *
+ * A share is three steps: POST /api/v1/stitches with the cut, whose media
+ * URLs are the bundle's `media/<id>.<ext>` names, one PUT per file to the
+ * upload link the response carries, and a POST to its publish link, which
+ * checks the files and the stills and makes the page live. The server
+ * rewrites the names to its own storage URLs; the printed link is the player
+ * page for that cut. The first share signs in (see login.ts).
+ */
+import type { ServedCut } from '@openstory/stitch/bundle';
+import type { CliContext, Command } from './context.js';
+export type ShareOptions = Pick<CliContext, 'home' | 'stderr' | 'open' | 'fetch'> & {
+    cut: ServedCut;
+    origin: string;
+    /** `--portrait-rights`: the basis for using a real person's likeness. */
+    portraitRights: string | null;
+};
+export declare const share: Command;
+/** Uploads the cut and returns the public link. */
+export declare function shareCut(options: ShareOptions): Promise<string>;

package/dist/share.js

@@ -0,0 +1,152 @@
+/**
+ * `openstory share`: upload a cut to OpenStory and get a link anyone can open.
+ *
+ * A share is three steps: POST /api/v1/stitches with the cut, whose media
+ * URLs are the bundle's `media/<id>.<ext>` names, one PUT per file to the
+ * upload link the response carries, and a POST to its publish link, which
+ * checks the files and the stills and makes the page live. The server
+ * rewrites the names to its own storage URLs; the printed link is the player
+ * page for that cut. The first share signs in (see login.ts).
+ */
+import { buildCut, bundledMediaUrl, cutJson, extensionOf, mediaType, parseCut, readBytes, } from '@openstory/stitch/bundle';
+import { errorInfo, errorText, recordOf } from './api.js';
+import { parseOrigin } from './context.js';
+import { signIn, storedKey } from './login.js';
+export const share = {
+    usage: 'openstory share [--origin url] [--portrait-rights basis] [cut options] <file>...',
+    async run(args, context) {
+        const { origin, rest } = parseOrigin(args);
+        let portraitRights = null;
+        const cutArgs = [];
+        for (let i = 0; i < rest.length; i++) {
+            const arg = rest[i] ?? '';
+            if (arg === '--portrait-rights') {
+                const value = rest[i + 1]?.trim();
+                if (value === undefined || value === '' || value.startsWith('-')) {
+                    throw new Error('--portrait-rights needs the basis for using the person’s likeness (a release reference, "self", a contract id)');
+                }
+                portraitRights = value;
+                i += 1;
+            }
+            else
+                cutArgs.push(arg);
+        }
+        const cut = await buildCut(await parseCut(cutArgs, context.cwd), bundledMediaUrl);
+        const url = await shareCut({ ...context, cut, origin, portraitRights });
+        context.stdout.write(`${url}\n`);
+    },
+};
+/** The extensions OpenStory stores for a stitch; the same list as its cut schema. */
+const SHARED_EXTENSIONS = new Set([
+    '.jpg',
+    '.jpeg',
+    '.png',
+    '.webp',
+    '.gif',
+    '.mp4',
+    '.webm',
+    '.mov',
+    '.mp3',
+    '.wav',
+    '.ogg',
+    '.m4a',
+]);
+/** Uploads the cut and returns the public link. */
+export async function shareCut(options) {
+    const fetchFn = options.fetch;
+    const origin = options.origin;
+    for (const file of options.cut.files.values()) {
+        const ext = extensionOf(file);
+        if (ext === '') {
+            throw new Error(`${file} has no file extension; share a copy that has one`);
+        }
+        if (!SHARED_EXTENSIONS.has(ext)) {
+            throw new Error(`${file}: ${ext} is not a type the shared player plays`);
+        }
+    }
+    let key = await storedKey(options.home, origin);
+    let fresh = false;
+    if (key === null) {
+        key = await signIn(options);
+        fresh = true;
+    }
+    let created = await createStitch(fetchFn, origin, key, options.cut);
+    if (!created.ok && created.status === 401 && !fresh) {
+        // The stored key was revoked. Sign in once more, then give up.
+        key = await signIn(options);
+        created = await createStitch(fetchFn, origin, key, options.cut);
+    }
+    if (!created.ok) {
+        throw created.status === 401
+            ? new Error('OpenStory refused the key')
+            : created.error;
+    }
+    const { url, uploadHref, publishHref } = created;
+    for (const [id, file] of options.cut.files) {
+        const name = bundledMediaUrl(id, file).slice('media/'.length);
+        const type = mediaType(file);
+        const target = new URL(uploadHref
+            .replace('{name}', encodeURIComponent(name))
+            .replace('{type}', encodeURIComponent(type)), origin);
+        // ponytail: the whole file sits in memory for the PUT; the upload route
+        // takes one body up to ~100 MB. Stream and use the multipart route past that.
+        const response = await fetchFn(target, {
+            method: 'PUT',
+            headers: { Authorization: `Bearer ${key}`, 'Content-Type': type },
+            body: new Uint8Array(await readBytes(file)),
+        });
+        if (!response.ok) {
+            throw new Error(`${file}: upload failed (${response.status}) ${await errorText(response)}`);
+        }
+    }
+    const published = await fetchFn(new URL(publishHref, origin), {
+        method: 'POST',
+        headers: {
+            Authorization: `Bearer ${key}`,
+            'Content-Type': 'application/json',
+        },
+        body: JSON.stringify({
+            portraitAttestation: options.portraitRights === null
+                ? null
+                : {
+                    statementVersion: 'portrait-rights-v1',
+                    authorizationBasis: options.portraitRights,
+                },
+        }),
+    });
+    if (!published.ok) {
+        const { code, text } = await errorInfo(published);
+        throw new Error(code === 'ATTESTATION_REQUIRED'
+            ? `${text} Run openstory share again with --portrait-rights <basis>.`
+            : `OpenStory did not publish the cut (${published.status}) ${text}`);
+    }
+    return url;
+}
+async function createStitch(fetchFn, origin, key, cut) {
+    const response = await fetchFn(new URL('/api/v1/stitches', origin), {
+        method: 'POST',
+        headers: {
+            Authorization: `Bearer ${key}`,
+            'Content-Type': 'application/json',
+        },
+        body: JSON.stringify({ cut: JSON.parse(cutJson(cut)) }),
+    });
+    if (!response.ok) {
+        return {
+            ok: false,
+            status: response.status,
+            error: new Error(`OpenStory did not take the cut (${response.status}) ${await errorText(response)}`),
+        };
+    }
+    const record = recordOf(await response.json());
+    const url = record.url;
+    const links = recordOf(record._links);
+    const uploadHref = recordOf(links.upload).href;
+    const publishHref = recordOf(links.publish).href;
+    if (typeof url !== 'string' ||
+        typeof uploadHref !== 'string' ||
+        typeof publishHref !== 'string') {
+        throw new Error('OpenStory answered without a link to upload to');
+    }
+    return { ok: true, url, uploadHref, publishHref };
+}

package/dist/sync.d.ts

@@ -0,0 +1,27 @@
+/**
+ * `openstory sync`: a one-way mirror of an organization's sequences into
+ * `<dir>/<organization>/<sequence-slug>/` (#2222). OpenStory writes; the folder
+ * is output only and nothing reads it back. A full pass runs at start, then a
+ * sequence is synced again a couple of seconds after its realtime events
+ * settle. Every pass is safe to repeat, so a missed event is fixed by the next.
+ *
+ * `<dir>/.openstory/sync.json` maps organization and sequence ids to folders,
+ * so a slug change renames the folder. Archived or deleted sequences drop out
+ * of the list and their folders are left alone.
+ */
+import type { Command } from './context.js';
+export type SyncState = {
+    v: 1;
+    origin: string;
+    organizations: Record<string, string>;
+    sequences: Record<string, {
+        organization: string;
+        folder: string;
+    }>;
+};
+export declare function readSyncState(dir: string, origin: string): Promise<SyncState>;
+/** The ids each `data:` frame of an SSE chunk names as its channel. */
+export declare function channelsInFrames(text: string): string[];
+/** Runs `job` once per id, `SETTLE_MS` after its last event, one job at a time. */
+export declare function settler(job: (id: string) => Promise<void>, onError: (error: unknown) => void, settleMs?: number): (id: string) => void;
+export declare const sync: Command;