photon-msg 0.0.0-stage → 0.1.0

package/dist/content.js

@@ -0,0 +1,287 @@
+/**
+ * Turns CLI flags into a Photon `SendContent` payload.
+ *
+ * The API takes one polymorphic `content` object, which is how edits, unsends,
+ * reactions, read receipts, typing indicators and poll votes travel: there is no
+ * separate endpoint per action. This module is the single source of truth for
+ * that mapping, and it stays pure by taking uploads and user lookups as injected
+ * dependencies.
+ */
+import { readFileSync } from "node:fs";
+import { usageError } from "./errors.js";
+/** Every content mode the CLI can build. */
+export const MODES = [
+    "text",
+    "attachment",
+    "voice",
+    "reaction",
+    "poll",
+    "edit",
+    "delete",
+    "read",
+    "typing",
+    "participants",
+    "group",
+];
+const asArray = (value) => value === undefined ? [] : Array.isArray(value) ? value : [value];
+const isSet = (value) => value !== undefined && value !== null && value !== false;
+/** Lists the content modes implied by the given flags. */
+export function detectModes(flags) {
+    const modes = [];
+    // An edit carries its replacement text, so --text belongs to the edit rather
+    // than being a competing mode.
+    const editing = isSet(flags.edit);
+    if (!editing && (isSet(flags.text) || isSet(flags["text-file"])))
+        modes.push("text");
+    if (asArray(flags.image).length > 0 || asArray(flags.file).length > 0)
+        modes.push("attachment");
+    if (isSet(flags.voice))
+        modes.push("voice");
+    if (isSet(flags.reaction))
+        modes.push("reaction");
+    if (isSet(flags.poll))
+        modes.push("poll");
+    if (editing)
+        modes.push("edit");
+    if (isSet(flags.delete))
+        modes.push("delete");
+    if (flags.read === true)
+        modes.push("read");
+    if (isSet(flags.typing))
+        modes.push("typing");
+    if (asArray(flags["participants-add"]).length > 0 || asArray(flags["participants-remove"]).length > 0) {
+        modes.push("participants");
+    }
+    if (flags.group === true)
+        modes.push("group");
+    return modes;
+}
+/** Reads text from a file, or stdin when the path is "-". */
+export function readTextFile(path) {
+    try {
+        return readFileSync(path === "-" ? 0 : path, "utf8");
+    }
+    catch (error) {
+        throw usageError(`Could not read ${path === "-" ? "stdin" : path}: ${error.message}`);
+    }
+}
+const normalizeFormat = (format) => {
+    if (!format)
+        return "plain";
+    const value = format.toLowerCase();
+    if (value !== "plain" && value !== "markdown") {
+        throw usageError(`--format must be "plain" or "markdown", got "${format}".`);
+    }
+    return value;
+};
+const textPart = (text, format) => ({ type: "text", format, text });
+/**
+ * Cheap, side-effect-free validation of content flags, so the CLI can refuse a
+ * contradictory command before it asks for credentials or touches the network.
+ */
+export function validateContentFlags(flags) {
+    const modes = detectModes(flags);
+    if (modes.length === 0) {
+        throw usageError("Nothing to send. Pass --text, --image, --poll, --reaction, --edit, and so on.", "Run `photon-msg send --help` for the full list.");
+    }
+    if (modes.length > 1 && !flags.group) {
+        throw usageError(`Conflicting content flags: ${modes.join(", ")}. Use one content flag, or add --group to send several parts together.`);
+    }
+    return modes;
+}
+/** Builds the send payload from flags. */
+export async function buildMessage({ flags, upload, getUsers }) {
+    const modes = validateContentFlags(flags);
+    const format = normalizeFormat(flags.format);
+    // --group overrides the single-mode rule: several parts travel together.
+    const mode = flags.group ? "group" : modes[0];
+    const replyTo = flags["reply-to"];
+    const initialTexts = asArray(flags.text);
+    const texts = initialTexts.length > 0
+        ? initialTexts
+        : flags["text-file"] !== undefined
+            ? [readTextFile(flags["text-file"])]
+            : [];
+    const attachmentSources = [...asArray(flags.image), ...asArray(flags.file)];
+    const build = async () => {
+        switch (mode) {
+            case "text": {
+                if (texts.length === 0)
+                    throw usageError("--text is empty.");
+                return { content: textPart(texts.join("\n"), format) };
+            }
+            case "attachment": {
+                const source = attachmentSources[0];
+                if (!source)
+                    throw usageError("--image needs a path or URL.");
+                const attachmentId = await upload(source);
+                const content = {
+                    type: "attachment",
+                    attachmentId,
+                    ...(flags.caption
+                        ? { metadata: { caption: { format, text: flags.caption } } }
+                        : {}),
+                };
+                return { content };
+            }
+            case "voice": {
+                if (!flags.voice)
+                    throw usageError("--voice needs a path.");
+                const attachmentId = await upload(flags.voice);
+                const content = { type: "voice", attachmentId };
+                return { content };
+            }
+            case "reaction": {
+                if (!replyTo)
+                    throw usageError("--reaction needs --reply-to <messageId> to name the message being reacted to.");
+                const action = flags["reaction-action"] ?? "add";
+                if (action !== "add" && action !== "remove") {
+                    throw usageError(`--reaction-action must be "add" or "remove", got "${action}".`);
+                }
+                const content = {
+                    type: "reaction",
+                    reaction: flags.reaction,
+                    action,
+                };
+                return { content, parentMessageId: replyTo };
+            }
+            case "poll": {
+                const options = asArray(flags["poll-option"]).map((text, index) => ({
+                    id: `opt_${index + 1}`,
+                    text,
+                }));
+                if (options.length === 0)
+                    throw usageError("--poll needs at least one --poll-option.");
+                const selectionMode = flags["poll-mode"] ?? "single";
+                if (selectionMode !== "single" && selectionMode !== "multiple") {
+                    throw usageError(`--poll-mode must be "single" or "multiple", got "${selectionMode}".`);
+                }
+                const content = {
+                    type: "poll",
+                    question: flags.poll,
+                    options,
+                    selectionMode,
+                };
+                return { content };
+            }
+            case "edit": {
+                if (texts.length === 0)
+                    throw usageError("--edit needs --text with the replacement text.");
+                const content = {
+                    type: "text.update",
+                    format,
+                    text: texts.join("\n"),
+                };
+                return { content, parentMessageId: flags.edit };
+            }
+            case "delete": {
+                const content = {
+                    type: "message.delete",
+                    ...(flags.reason ? { reason: flags.reason } : {}),
+                };
+                return { content, parentMessageId: flags.delete };
+            }
+            case "read": {
+                if (!replyTo)
+                    throw usageError("--read needs --reply-to <messageId> to name the message being marked read.");
+                const content = { type: "message.read" };
+                return { content, parentMessageId: replyTo };
+            }
+            case "typing": {
+                const raw = String(flags.typing).toLowerCase();
+                const typing = raw === "on" || raw === "true" || raw === "1";
+                if (!typing && raw !== "off" && raw !== "false" && raw !== "0") {
+                    throw usageError(`--typing must be "on" or "off", got "${flags.typing}".`);
+                }
+                const content = { type: "space.typing.update", typing };
+                return { content };
+            }
+            case "participants": {
+                const added = asArray(flags["participants-add"]);
+                const removed = asArray(flags["participants-remove"]);
+                const users = await getUsers([...added, ...removed]);
+                const byId = new Map(users.map((user) => [user.id, user]));
+                const snapshot = (id) => {
+                    const user = byId.get(id);
+                    if (!user)
+                        throw usageError(`Unknown user ID "${id}".`);
+                    // The API accepts the user record it returned as the snapshot input.
+                    return user;
+                };
+                const content = {
+                    type: "space.participants.update",
+                    added: added.map(snapshot),
+                    removed: removed.map(snapshot),
+                };
+                return { content };
+            }
+            case "group": {
+                const uploads = attachmentSources.length + (isSet(flags.voice) ? 1 : 0);
+                if (texts.length + uploads < 2) {
+                    throw usageError('--group needs at least two parts, for example --text "a" --image ./b.png.');
+                }
+                const parts = texts.map((text) => textPart(text, format));
+                for (const source of attachmentSources) {
+                    const attachmentId = await upload(source);
+                    parts.push({ type: "attachment", attachmentId });
+                }
+                if (flags.voice) {
+                    const attachmentId = await upload(flags.voice);
+                    parts.push({ type: "voice", attachmentId });
+                }
+                const content = { type: "group", parts };
+                return { content };
+            }
+            default: {
+                const exhaustive = mode;
+                throw usageError(`Unsupported content mode "${String(exhaustive)}".`);
+            }
+        }
+    };
+    const built = await build();
+    const result = { content: built.content };
+    if (built.parentMessageId)
+        result.parentMessageId = built.parentMessageId;
+    const cc = asArray(flags.cc);
+    const bcc = asArray(flags.bcc);
+    if (flags.subject || cc.length > 0 || bcc.length > 0) {
+        result.email = {
+            ...(flags.subject ? { subject: flags.subject } : {}),
+            ...(cc.length > 0 ? { cc: cc.map((address) => ({ address })) } : {}),
+            ...(bcc.length > 0 ? { bcc: bcc.map((address) => ({ address })) } : {}),
+        };
+    }
+    return result;
+}
+/** Short human description of a payload, used by --dry-run and logs. */
+export function describeContent(content) {
+    if (!content)
+        return "nothing";
+    switch (content.type) {
+        case "text":
+            return `text(${content.format}): ${JSON.stringify(content.text)}`;
+        case "text.update":
+            return `edit(${content.format}): ${JSON.stringify(content.text)}`;
+        case "attachment":
+            return `attachment(${content.attachmentId})`;
+        case "voice":
+            return `voice(${content.attachmentId})`;
+        case "reaction":
+            return `reaction(${content.action ?? "add"} ${content.reaction})`;
+        case "poll":
+            return `poll(${JSON.stringify(content.question)}, ${content.options.length} options)`;
+        case "message.delete":
+            return "delete";
+        case "message.read":
+            return "read receipt";
+        case "space.typing.update":
+            return `typing(${content.typing ? "on" : "off"})`;
+        case "space.participants.update":
+            return `participants(+${content.added.length}/-${content.removed.length})`;
+        case "group":
+            return `group(${content.parts.length} parts)`;
+        default:
+            return "unknown content";
+    }
+}
+//# sourceMappingURL=content.js.map

package/dist/content.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"content.js","sourceRoot":"","sources":["../src/content.ts"],"names":[],"mappings":"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"}

package/dist/errors.d.ts

@@ -0,0 +1,62 @@
+/**
+ * Error types and exit codes.
+ *
+ * Every failure path funnels through `CliError`, so callers always get a stable
+ * `exitCode` plus an optional actionable `hint`.
+ */
+export declare const EXIT: {
+    readonly OK: 0;
+    readonly FAILURE: 1;
+    readonly USAGE: 2;
+    readonly AUTH: 3;
+    readonly NOT_FOUND: 4;
+    readonly FORBIDDEN: 5;
+    readonly CONFLICT: 6;
+};
+export type ExitCode = (typeof EXIT)[keyof typeof EXIT];
+export interface CliErrorOptions {
+    exitCode?: number;
+    hint?: string;
+    code?: string;
+    details?: unknown;
+}
+export declare class CliError extends Error {
+    readonly exitCode: number;
+    readonly hint?: string;
+    readonly code?: string;
+    readonly details?: unknown;
+    constructor(message: string, options?: CliErrorOptions);
+}
+/** Usage error: bad flags, missing required arguments. */
+export declare const usageError: (message: string, hint?: string) => CliError;
+/** Problem codes the API returns, mapped to guidance. */
+export declare const PROBLEM_HINTS: Record<string, string>;
+/** The shape of an API problem document. */
+export interface ProblemBody {
+    code?: string;
+    detail?: string;
+    title?: string;
+    requestId?: string;
+    type?: string;
+    [key: string]: unknown;
+}
+/** Structural type of an `@photon-ai/api` error, without importing the class. */
+export interface ApiErrorLike {
+    status: number;
+    message: string;
+    body?: ProblemBody;
+}
+export declare const isApiError: (error: unknown) => error is ApiErrorLike;
+/** Normalizes anything thrown into a CliError. */
+export declare function toCliError(error: unknown): CliError;
+/** Serializes an error for `--json` output. */
+export declare const errorPayload: (cliError: CliError) => {
+    error: {
+        message: string;
+        code: string | null;
+        exitCode: number;
+        hint: string | null;
+        details: {} | null;
+    };
+};
+//# sourceMappingURL=errors.d.ts.map

package/dist/errors.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,eAAO,MAAM,IAAI;;;;;;;;CAQP,CAAC;AAEX,MAAM,MAAM,QAAQ,GAAG,CAAC,OAAO,IAAI,CAAC,CAAC,MAAM,OAAO,IAAI,CAAC,CAAC;AAExD,MAAM,WAAW,eAAe;IAC9B,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,OAAO,CAAC,EAAE,OAAO,CAAC;CACnB;AAED,qBAAa,QAAS,SAAQ,KAAK;IACjC,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,OAAO,CAAC,EAAE,OAAO,CAAC;gBAEf,OAAO,EAAE,MAAM,EAAE,OAAO,GAAE,eAAoB;CAQ3D;AAED,0DAA0D;AAC1D,eAAO,MAAM,UAAU,GAAI,SAAS,MAAM,EAAE,OAAO,MAAM,KAAG,QACU,CAAC;AAEvE,yDAAyD;AACzD,eAAO,MAAM,aAAa,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAmBhD,CAAC;AAWF,4CAA4C;AAC5C,MAAM,WAAW,WAAW;IAC1B,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC;CACxB;AAED,iFAAiF;AACjF,MAAM,WAAW,YAAY;IAC3B,MAAM,EAAE,MAAM,CAAC;IACf,OAAO,EAAE,MAAM,CAAC;IAChB,IAAI,CAAC,EAAE,WAAW,CAAC;CACpB;AAED,eAAO,MAAM,UAAU,GAAI,OAAO,OAAO,KAAG,KAAK,IAAI,YAIS,CAAC;AAE/D,kDAAkD;AAClD,wBAAgB,UAAU,CAAC,KAAK,EAAE,OAAO,GAAG,QAAQ,CAsBnD;AAED,+CAA+C;AAC/C,eAAO,MAAM,YAAY,GAAI,UAAU,QAAQ;;;;;;;;CAQ7C,CAAC"}

package/dist/errors.js

@@ -0,0 +1,95 @@
+/**
+ * Error types and exit codes.
+ *
+ * Every failure path funnels through `CliError`, so callers always get a stable
+ * `exitCode` plus an optional actionable `hint`.
+ */
+export const EXIT = {
+    OK: 0,
+    FAILURE: 1,
+    USAGE: 2,
+    AUTH: 3,
+    NOT_FOUND: 4,
+    FORBIDDEN: 5,
+    CONFLICT: 6,
+};
+export class CliError extends Error {
+    exitCode;
+    hint;
+    code;
+    details;
+    constructor(message, options = {}) {
+        super(message);
+        this.name = "CliError";
+        this.exitCode = options.exitCode ?? EXIT.FAILURE;
+        this.hint = options.hint;
+        this.code = options.code;
+        this.details = options.details;
+    }
+}
+/** Usage error: bad flags, missing required arguments. */
+export const usageError = (message, hint) => new CliError(message, { exitCode: EXIT.USAGE, hint, code: "USAGE" });
+/** Problem codes the API returns, mapped to guidance. */
+export const PROBLEM_HINTS = {
+    SHARED_LINE_INBOUND_REQUIRED: "This line is a pooled shared line, so it cannot message someone who has not written to it first. " +
+        "Have the recipient send any message to the line, then reply inside that space. " +
+        "For agent-initiated messages you need a purchased SMS number or a dedicated iMessage line.",
+    SHARED_LINE_GROUP_UNSUPPORTED: "Pooled shared lines only carry direct conversations, not group chats.",
+    NOT_AUTHENTICATED: "Set PHOTON_API_KEY to a project API key, or pass --api-key.",
+    INSUFFICIENT_SCOPE: "The API key is missing a permission this call needs. Project keys need project:read / project:write; " +
+        "line assignments also need platforms:read / platforms:write.",
+    FORBIDDEN: "The key is valid but not allowed to touch this resource. Check the project ID and key scope.",
+    PROJECT_NOT_SELECTED: "Set PHOTON_PROJECT_ID, or pass --project.",
+    IDEMPOTENCY_KEY_REUSED: "That idempotency key was already used for a different request. Omit --idempotency-key to mint a new one.",
+    VALIDATION_FAILED: "The API rejected the payload. Re-run with --json to see the full problem detail.",
+    ATTACHMENT_NOT_READY: "The attachment is still processing. Retry after the server's Retry-After interval.",
+    RATE_LIMITED: "Rate limited. Honor the Retry-After header instead of retrying immediately.",
+    ATTACHMENT_TOO_LARGE: "The file exceeds the attachment size limit.",
+    UNSUPPORTED_CONTENT: "This platform does not support that content type. Check the platform's feature support.",
+};
+const EXIT_BY_STATUS = {
+    401: EXIT.AUTH,
+    403: EXIT.FORBIDDEN,
+    404: EXIT.NOT_FOUND,
+    409: EXIT.CONFLICT,
+    422: EXIT.USAGE,
+    429: EXIT.FAILURE,
+};
+export const isApiError = (error) => typeof error === "object" &&
+    error !== null &&
+    typeof error.status === "number" &&
+    typeof error.message === "string";
+/** Normalizes anything thrown into a CliError. */
+export function toCliError(error) {
+    if (error instanceof CliError)
+        return error;
+    if (isApiError(error)) {
+        const problem = error.body ?? {};
+        const code = problem.code ?? `HTTP_${error.status}`;
+        const detail = problem.detail ?? problem.title ?? error.message;
+        const exitCode = EXIT_BY_STATUS[error.status] ?? EXIT.FAILURE;
+        return new CliError(`Photon API error ${error.status}: ${detail}`, {
+            exitCode,
+            code,
+            hint: PROBLEM_HINTS[code],
+            details: {
+                code,
+                status: error.status,
+                requestId: problem.requestId,
+                type: problem.type,
+            },
+        });
+    }
+    return new CliError(error instanceof Error ? error.message : String(error));
+}
+/** Serializes an error for `--json` output. */
+export const errorPayload = (cliError) => ({
+    error: {
+        message: cliError.message,
+        code: cliError.code ?? null,
+        exitCode: cliError.exitCode,
+        hint: cliError.hint ?? null,
+        details: cliError.details ?? null,
+    },
+});
+//# sourceMappingURL=errors.js.map

package/dist/errors.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.js","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,MAAM,CAAC,MAAM,IAAI,GAAG;IAClB,EAAE,EAAE,CAAC;IACL,OAAO,EAAE,CAAC;IACV,KAAK,EAAE,CAAC;IACR,IAAI,EAAE,CAAC;IACP,SAAS,EAAE,CAAC;IACZ,SAAS,EAAE,CAAC;IACZ,QAAQ,EAAE,CAAC;CACH,CAAC;AAWX,MAAM,OAAO,QAAS,SAAQ,KAAK;IACxB,QAAQ,CAAS;IACjB,IAAI,CAAU;IACd,IAAI,CAAU;IACd,OAAO,CAAW;IAE3B,YAAY,OAAe,EAAE,UAA2B,EAAE;QACxD,KAAK,CAAC,OAAO,CAAC,CAAC;QACf,IAAI,CAAC,IAAI,GAAG,UAAU,CAAC;QACvB,IAAI,CAAC,QAAQ,GAAG,OAAO,CAAC,QAAQ,IAAI,IAAI,CAAC,OAAO,CAAC;QACjD,IAAI,CAAC,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC;QACzB,IAAI,CAAC,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC;QACzB,IAAI,CAAC,OAAO,GAAG,OAAO,CAAC,OAAO,CAAC;IACjC,CAAC;CACF;AAED,0DAA0D;AAC1D,MAAM,CAAC,MAAM,UAAU,GAAG,CAAC,OAAe,EAAE,IAAa,EAAY,EAAE,CACrE,IAAI,QAAQ,CAAC,OAAO,EAAE,EAAE,QAAQ,EAAE,IAAI,CAAC,KAAK,EAAE,IAAI,EAAE,IAAI,EAAE,OAAO,EAAE,CAAC,CAAC;AAEvE,yDAAyD;AACzD,MAAM,CAAC,MAAM,aAAa,GAA2B;IACnD,4BAA4B,EAC1B,mGAAmG;QACnG,iFAAiF;QACjF,4FAA4F;IAC9F,6BAA6B,EAAE,uEAAuE;IACtG,iBAAiB,EAAE,6DAA6D;IAChF,kBAAkB,EAChB,uGAAuG;QACvG,8DAA8D;IAChE,SAAS,EAAE,8FAA8F;IACzG,oBAAoB,EAAE,2CAA2C;IACjE,sBAAsB,EACpB,0GAA0G;IAC5G,iBAAiB,EAAE,kFAAkF;IACrG,oBAAoB,EAAE,oFAAoF;IAC1G,YAAY,EAAE,6EAA6E;IAC3F,oBAAoB,EAAE,6CAA6C;IACnE,mBAAmB,EAAE,yFAAyF;CAC/G,CAAC;AAEF,MAAM,cAAc,GAA2B;IAC7C,GAAG,EAAE,IAAI,CAAC,IAAI;IACd,GAAG,EAAE,IAAI,CAAC,SAAS;IACnB,GAAG,EAAE,IAAI,CAAC,SAAS;IACnB,GAAG,EAAE,IAAI,CAAC,QAAQ;IAClB,GAAG,EAAE,IAAI,CAAC,KAAK;IACf,GAAG,EAAE,IAAI,CAAC,OAAO;CAClB,CAAC;AAmBF,MAAM,CAAC,MAAM,UAAU,GAAG,CAAC,KAAc,EAAyB,EAAE,CAClE,OAAO,KAAK,KAAK,QAAQ;IACzB,KAAK,KAAK,IAAI;IACd,OAAQ,KAA8B,CAAC,MAAM,KAAK,QAAQ;IAC1D,OAAQ,KAA+B,CAAC,OAAO,KAAK,QAAQ,CAAC;AAE/D,kDAAkD;AAClD,MAAM,UAAU,UAAU,CAAC,KAAc;IACvC,IAAI,KAAK,YAAY,QAAQ;QAAE,OAAO,KAAK,CAAC;IAE5C,IAAI,UAAU,CAAC,KAAK,CAAC,EAAE,CAAC;QACtB,MAAM,OAAO,GAAG,KAAK,CAAC,IAAI,IAAI,EAAE,CAAC;QACjC,MAAM,IAAI,GAAG,OAAO,CAAC,IAAI,IAAI,QAAQ,KAAK,CAAC,MAAM,EAAE,CAAC;QACpD,MAAM,MAAM,GAAG,OAAO,CAAC,MAAM,IAAI,OAAO,CAAC,KAAK,IAAI,KAAK,CAAC,OAAO,CAAC;QAChE,MAAM,QAAQ,GAAG,cAAc,CAAC,KAAK,CAAC,MAAM,CAAC,IAAI,IAAI,CAAC,OAAO,CAAC;QAC9D,OAAO,IAAI,QAAQ,CAAC,oBAAoB,KAAK,CAAC,MAAM,KAAK,MAAM,EAAE,EAAE;YACjE,QAAQ;YACR,IAAI;YACJ,IAAI,EAAE,aAAa,CAAC,IAAI,CAAC;YACzB,OAAO,EAAE;gBACP,IAAI;gBACJ,MAAM,EAAE,KAAK,CAAC,MAAM;gBACpB,SAAS,EAAE,OAAO,CAAC,SAAS;gBAC5B,IAAI,EAAE,OAAO,CAAC,IAAI;aACnB;SACF,CAAC,CAAC;IACL,CAAC;IAED,OAAO,IAAI,QAAQ,CAAC,KAAK,YAAY,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC,CAAC;AAC9E,CAAC;AAED,+CAA+C;AAC/C,MAAM,CAAC,MAAM,YAAY,GAAG,CAAC,QAAkB,EAAE,EAAE,CAAC,CAAC;IACnD,KAAK,EAAE;QACL,OAAO,EAAE,QAAQ,CAAC,OAAO;QACzB,IAAI,EAAE,QAAQ,CAAC,IAAI,IAAI,IAAI;QAC3B,QAAQ,EAAE,QAAQ,CAAC,QAAQ;QAC3B,IAAI,EAAE,QAAQ,CAAC,IAAI,IAAI,IAAI;QAC3B,OAAO,EAAE,QAAQ,CAAC,OAAO,IAAI,IAAI;KAClC;CACF,CAAC,CAAC"}

package/dist/help.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Help text. Kept as data so `--help` output stays consistent across commands.
+ */
+/** Single source of truth for the version: package.json. */
+export declare const VERSION: string;
+export declare const MAIN_HELP: string;
+export declare const COMMAND_HELP: Record<string, string>;
+//# sourceMappingURL=help.d.ts.map

package/dist/help.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"help.d.ts","sourceRoot":"","sources":["../src/help.ts"],"names":[],"mappings":"AAAA;;GAEG;AAuCH,4DAA4D;AAC5D,eAAO,MAAM,OAAO,EAAE,MAAsB,CAAC;AAE7C,eAAO,MAAM,SAAS,QAyDrB,CAAC;AAEF,eAAO,MAAM,YAAY,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAgF/C,CAAC"}

package/dist/help.js

@@ -0,0 +1,177 @@
+/**
+ * Help text. Kept as data so `--help` output stays consistent across commands.
+ */
+import { existsSync, readFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+/**
+ * Reads the version from the nearest package.json.
+ *
+ * This module can be loaded from `dist/` (published) or `.test-build/src/`
+ * (compiled tests), so the manifest is found by walking up rather than assuming
+ * a fixed depth. Walking up also survives a change to the output layout.
+ */
+function readVersion() {
+    let directory = dirname(fileURLToPath(import.meta.url));
+    for (let depth = 0; depth < 5; depth += 1) {
+        const candidate = join(directory, "package.json");
+        if (existsSync(candidate)) {
+            try {
+                const pkg = JSON.parse(readFileSync(candidate, "utf8"));
+                if (pkg.version && (pkg.name === undefined || pkg.name === "photon-msg")) {
+                    return pkg.version;
+                }
+            }
+            catch {
+                // Fall through to the parent directory.
+            }
+        }
+        const parent = dirname(directory);
+        if (parent === directory)
+            break;
+        directory = parent;
+    }
+    return "0.0.0";
+}
+/** Single source of truth for the version: package.json. */
+export const VERSION = readVersion();
+export const MAIN_HELP = `photon-msg ${VERSION} — send and read messages through the Photon API
+
+USAGE
+  photon-msg <command> [options]
+
+COMMANDS
+  send               Send any content type: text, image, voice, poll, reaction, edit, unsend
+  messages list      List messages with filters
+  messages get       Fetch one message
+  messages watch     Follow new messages as JSON lines
+  spaces list        List conversations
+  spaces get         Fetch one conversation
+  spaces create      Create or reuse a conversation
+  users list         List people and agents in the project
+  users get          Fetch one user
+  users ensure       Resolve a handle to a user ID
+  attachments upload Upload a file or URL
+  attachments get    Inspect attachment metadata
+  attachments download  Write attachment bytes to disk
+  typing             Start or stop a typing indicator
+  read               Mark a message read
+  line assign        Assign a pooled iMessage line to a handle
+  line list          List shared-line assignments
+  line get           Fetch one assignment
+  line release       Release an assignment
+  doctor             Check credentials and project wiring
+  help               Show this help
+
+GLOBAL OPTIONS
+  --json               Machine-readable output
+  --no-color           Disable ANSI color
+  --api-key <key>      Project API key (or PHOTON_API_KEY)
+  --project <id>       Project ID (or PHOTON_PROJECT_ID)
+  --base-url <url>     API origin (or PHOTON_API_BASE_URL)
+  --timeout <ms>       Per-request timeout
+  --dry-run            Print the request instead of sending it
+  --quiet, -q          Suppress the summary lines
+  --help, -h           Show help
+  --version, -v        Show version
+
+ADDRESSING
+  --space <spaceId> --as <agent>    reply into an existing conversation
+  --to <handle> --as <agent>        start or reuse a direct conversation
+  --as accepts a handle or a pho_usr_ ID; PHOTON_AGENT_HANDLE is the default.
+
+EXAMPLES
+  photon-msg send --to +14155550123 --as +16285024649 --text "hello"
+  photon-msg send --space pho_spc_... --as pho_usr_... --image ./photo.png --caption "look"
+  photon-msg send --space pho_spc_... --as pho_usr_... --poll "Lunch?" --poll-option Yes --poll-option No
+  photon-msg send --space pho_spc_... --as pho_usr_... --reply-to pho_msg_... --reaction "❤️"
+  photon-msg send --space pho_spc_... --as pho_usr_... --edit pho_msg_... --text "fixed typo"
+  photon-msg messages list --platform imessage --direction received --limit 20
+  photon-msg line assign --handle +14155550123
+
+Addressing a new conversation requires a line that may start it. Pooled shared
+lines cannot: the recipient must message the line first, and the API answers
+403 SHARED_LINE_INBOUND_REQUIRED until they do.
+`;
+export const COMMAND_HELP = {
+    send: `photon-msg send — send one message
+
+DESTINATION
+  --space <spaceId>       Existing conversation (reply, edit, reaction, ...)
+  --to <handle>           Start or reuse a direct conversation with this handle
+  --as <handle|userId>    Sender agent (default: PHOTON_AGENT_HANDLE)
+  --platform <name>       imessage | sms | email | whatsapp | whatsapp_business | telegram
+
+CONTENT (choose one, or combine with --group)
+  --text <string>         Text body (repeatable; lines are joined)
+  --text-file <path>      Read the body from a file, or "-" for stdin
+  --format <plain|markdown>
+  --image <path|url>      Image attachment (repeatable)
+  --file <path|url>       Any attachment (repeatable)
+  --caption <string>      Caption for a single attachment
+  --voice <path>          Voice note
+  --poll <question> --poll-option <text> [--poll-option ...] [--poll-mode single|multiple]
+  --reaction <emoji> [--reaction-action add|remove]   needs --reply-to
+  --edit <messageId> --text <new text>                edit a sent message
+  --delete <messageId> [--reason <text>]              unsend a message
+  --read                          read receipt, needs --reply-to
+  --typing <on|off>               typing indicator as content
+  --participants-add <userId> --participants-remove <userId>
+  --group                         send the supplied parts as one group
+
+OTHER
+  --reply-to <messageId>  Thread the message under another
+  --idempotency-key <key> Reuse across retries of the same logical send
+  --subject/--cc/--bcc    Email-only options
+
+Acceptance is asynchronous: a successful send means the API queued the message,
+not that the recipient has seen it.
+`,
+    "messages list": `photon-msg messages list — list messages
+
+  --platform <name>          Restrict to one platform
+  --direction received|dispatched
+  --space <spaceId>          Restrict to a conversation
+  --resource <resourceId>    Restrict to a resource
+  --perspective-user <id>    Restrict to one user's view (needs --space)
+  --created-since/--created-before   RFC 3339 bounds on createdAt
+  --updated-since/--updated-before   RFC 3339 bounds on updatedAt
+  --exclude-content-types <list>     Comma-separated content types
+  --order asc|desc  --order-by <field>
+  --page-size <n>  --page-token <token>  --limit <n>
+`,
+    "messages watch": `photon-msg messages watch — follow new messages as JSON lines
+
+  --platform <name>  --space <spaceId>  --direction <dir>
+  --interval <seconds>   Poll interval (default 2)
+  --for <seconds>        Stop after this long (default: run until interrupted)
+  --since <rfc3339>      Start point (default: now)
+`,
+    "spaces create": `photon-msg spaces create — create or reuse a conversation
+
+  --platform <name>
+  --participant <handle|userId>   Repeatable; order matters on iMessage (first is creator)
+  --idempotency-key <key>
+`,
+    "users ensure": `photon-msg users ensure — resolve a handle to a user ID
+
+  --handle <handle>    Phone (E.164) or email
+  --platform <name>
+`,
+    "attachments upload": `photon-msg attachments upload — upload a file or URL
+
+  <path|url>  --content-type <mime>
+`,
+    typing: `photon-msg typing — typing indicator
+
+  --space <spaceId>  --as <agent>  --on | --off
+`,
+    "line assign": `photon-msg line assign — assign a pooled iMessage line
+
+  --handle <+15551234567>   The human who will write to the line
+  --email <address>         Optional invite address
+  --first-name/--last-name
+  --idempotency-key <key>   Reuse for retries of the same assignment
+`,
+};
+//# sourceMappingURL=help.js.map