chatbase 0.0.1 → 0.1.1

package/dist/commands/tickets/create.js

@@ -0,0 +1,58 @@
+import { Flags } from '@oclif/core';
+import { AgentCommand } from '../../base/agent-command.js';
+import { bodyFieldFlags } from '../../base/base-command.js';
+import { readBodyData } from '../../base/body-input.js';
+import { throwIfError } from '../../client/client.js';
+export default class TicketsCreate extends AgentCommand {
+    static description = 'Create a helpdesk ticket';
+    static examples = [
+        '<%= config.bin %> tickets create --subject "Export failing" -f description="Customer cannot export." --customer-email jane@example.com -a agt_123',
+        '<%= config.bin %> tickets create --subject "Export failing" --data \'{"description":"Customer cannot export.","customer":{"email":"jane@example.com"}}\' -a agt_123'
+    ];
+    static flags = {
+        ...AgentCommand.baseFlags,
+        ...bodyFieldFlags,
+        subject: Flags.string({ description: 'Ticket subject' }),
+        'customer-email': Flags.string({
+            description: 'Customer email — builds the required customer object (alternative to customer in --data)'
+        }),
+        'customer-name': Flags.string({
+            description: 'Customer display name, used only when the email creates a new customer record',
+            dependsOn: ['customer-email']
+        }),
+        data: Flags.string({
+            description: 'JSON body (@file, @-, or inline). Fields: subject, description, customer, statusId, statusCategory, assigneeId, assigneeEmail, teamId'
+        })
+    };
+    async run() {
+        const { flags } = await this.parse(TicketsCreate);
+        const customerEmail = flags['customer-email'];
+        const body = {
+            ...(await readBodyData(flags.data, flags.field)),
+            ...(flags.subject && { subject: flags.subject }),
+            ...(customerEmail && {
+                customer: {
+                    email: customerEmail,
+                    ...(flags['customer-name'] && {
+                        name: flags['customer-name']
+                    })
+                }
+            })
+        };
+        const client = this.apiClient(flags);
+        const agentId = await this.agentId(flags, client);
+        const { data, error, response } = await client.POST('/agents/{agentId}/helpdesk/tickets', {
+            params: { path: { agentId } },
+            body: body
+        });
+        throwIfError(response, error);
+        const ticketNumber = data.ticketNumber;
+        if (flags.json) {
+            process.stdout.write(`${JSON.stringify(data, null, 2)}\n`);
+        }
+        else {
+            this.success(flags, `Created ticket ${ticketNumber}`);
+            process.stdout.write(`${ticketNumber}\n`);
+        }
+    }
+}

package/dist/commands/tickets/get.js

@@ -0,0 +1,44 @@
+import { Args } from '@oclif/core';
+import { AgentCommand } from '../../base/agent-command.js';
+import { throwIfError } from '../../client/client.js';
+const COLUMNS = [
+    { key: 'ticketNumber', header: 'TICKET' },
+    { key: 'subject', header: 'SUBJECT' },
+    { key: 'statusCategory', header: 'STATUS' },
+    { key: 'channel', header: 'CHANNEL' },
+    { key: 'createdAt', header: 'CREATED' }
+];
+export default class TicketsGet extends AgentCommand {
+    static description = 'Show one helpdesk ticket';
+    static examples = ['<%= config.bin %> tickets get 42 -a agt_123'];
+    static args = {
+        ticketNumber: Args.integer({
+            required: true,
+            description: 'Ticket number'
+        })
+    };
+    static flags = { ...AgentCommand.baseFlags };
+    async run() {
+        const { args, flags } = await this.parse(TicketsGet);
+        const client = this.apiClient(flags);
+        const agentId = await this.agentId(flags, client);
+        const { data, error, response } = await client.GET('/agents/{agentId}/helpdesk/tickets/{ticketNumber}', {
+            params: {
+                path: { agentId, ticketNumber: args.ticketNumber }
+            }
+        });
+        throwIfError(response, error);
+        // GET .../tickets/{ticketNumber} returns the Ticket directly (no
+        // {data, pagination} envelope) — --json prints it as-is.
+        const ticket = data;
+        this.printData(flags, data, [
+            {
+                ticketNumber: String(ticket.ticketNumber ?? ''),
+                subject: String(ticket.subject ?? ''),
+                statusCategory: String(ticket.statusCategory ?? ''),
+                channel: String(ticket.channel ?? ''),
+                createdAt: String(ticket.createdAt ?? '')
+            }
+        ], COLUMNS);
+    }
+}

package/dist/commands/tickets/list.js

@@ -0,0 +1,96 @@
+import { Flags } from '@oclif/core';
+import { ListCommand } from '../../base/list-command.js';
+import { fetchPages } from '../../client/paginate.js';
+const COLUMNS = [
+    { key: 'ticketNumber', header: 'TICKET' },
+    { key: 'subject', header: 'SUBJECT' },
+    { key: 'statusCategory', header: 'STATUS' },
+    { key: 'channel', header: 'CHANNEL' },
+    { key: 'createdAt', header: 'CREATED' }
+];
+export default class TicketsList extends ListCommand {
+    static description = 'List helpdesk tickets for an agent';
+    static examples = [
+        '<%= config.bin %> tickets list -a agt_123',
+        '<%= config.bin %> tickets list -a agt_123 --status new,on_you',
+        '<%= config.bin %> tickets list -a agt_123 --all --json'
+    ];
+    static flags = {
+        ...ListCommand.baseFlags,
+        status: Flags.string({
+            description: 'Filter by status (comma-separated): new, on_you, on_customer, on_hold, closed, cancelled'
+        }),
+        channel: Flags.string({
+            description: 'Filter by channel (comma-separated, e.g. email,api)'
+        }),
+        'assignee-id': Flags.string({
+            description: 'Filter by assignee UUID, or "none" for unassigned'
+        }),
+        'team-id': Flags.string({
+            description: 'Filter by team UUID, or "none" for no team'
+        }),
+        'created-after': Flags.string({
+            description: 'Only tickets created after this ISO 8601 date'
+        }),
+        'created-before': Flags.string({
+            description: 'Only tickets created before this ISO 8601 date'
+        }),
+        'sort-by': Flags.string({
+            description: 'Sort field',
+            options: ['createdAt', 'updatedAt', 'lastMessageAt']
+        }),
+        order: Flags.string({
+            description: 'Sort direction',
+            options: ['asc', 'desc']
+        }),
+        'include-total': Flags.boolean({
+            description: 'Include pagination.total in the response'
+        })
+    };
+    async run() {
+        const { flags } = await this.parse(TicketsList);
+        const client = this.apiClient(flags);
+        const agentId = await this.agentId(flags, client);
+        const extraQuery = {};
+        if (flags.status)
+            extraQuery.status = flags.status;
+        if (flags.channel)
+            extraQuery.channel = flags.channel;
+        if (flags['assignee-id'])
+            extraQuery.assigneeId = flags['assignee-id'];
+        if (flags['team-id'])
+            extraQuery.teamId = flags['team-id'];
+        if (flags['created-after'])
+            extraQuery.createdAfter = flags['created-after'];
+        if (flags['created-before'])
+            extraQuery.createdBefore = flags['created-before'];
+        if (flags['sort-by'])
+            extraQuery.sortBy = flags['sort-by'];
+        if (flags.order)
+            extraQuery.order = flags.order;
+        if (flags['include-total'])
+            extraQuery.includeTotal = true;
+        const { pages, items } = await fetchPages((query) => client.GET('/agents/{agentId}/helpdesk/tickets', {
+            params: {
+                path: { agentId },
+                query: { ...query, ...extraQuery }
+            }
+        }), { limit: flags.limit, cursor: flags.cursor, all: flags.all });
+        const rows = items.map((t) => ({
+            ticketNumber: String(t.ticketNumber ?? ''),
+            subject: String(t.subject ?? ''),
+            statusCategory: String(t.statusCategory ?? ''),
+            channel: String(t.channel ?? ''),
+            createdAt: String(t.createdAt ?? '')
+        }));
+        const last = pages.at(-1);
+        // --json must stay the raw API shape even when --all merges pages
+        const raw = pages.length === 1
+            ? pages[0]
+            : { data: items, pagination: last?.pagination };
+        this.printData(flags, raw, rows, COLUMNS);
+        if (!flags.all && last?.pagination.hasMore && last.pagination.cursor) {
+            this.note(flags, `More results: rerun with --cursor ${last.pagination.cursor} (or use --all)`);
+        }
+    }
+}

package/dist/commands/tickets/messages.js

@@ -0,0 +1,87 @@
+import { Args, Flags } from '@oclif/core';
+import { ListCommand } from '../../base/list-command.js';
+import { fetchPages } from '../../client/paginate.js';
+import { UsageError } from '../../errors/errors.js';
+const COLUMNS = [
+    { key: 'id', header: 'ID' },
+    { key: 'type', header: 'TYPE' },
+    { key: 'sender', header: 'SENDER' },
+    { key: 'content', header: 'CONTENT' },
+    { key: 'createdAt', header: 'CREATED' }
+];
+function senderLabel(sender) {
+    if (!sender)
+        return '';
+    return sender.name ?? sender.email ?? sender.type ?? '';
+}
+export default class TicketsMessages extends ListCommand {
+    static description = "List a ticket's message thread";
+    static examples = [
+        '<%= config.bin %> tickets messages 42 -a agt_123',
+        '<%= config.bin %> tickets messages 42 -a agt_123 --all --json'
+    ];
+    static args = {
+        ticketNumber: Args.integer({
+            required: false,
+            description: 'Ticket number (alternative to --ticket)'
+        })
+    };
+    static flags = {
+        ...ListCommand.baseFlags,
+        ticket: Flags.integer({
+            description: 'Ticket number'
+        }),
+        types: Flags.string({
+            description: 'Message types to include (comma-separated): reply, note, event (default: reply,note)'
+        }),
+        order: Flags.string({
+            description: 'Sort direction',
+            options: ['asc', 'desc']
+        })
+    };
+    async run() {
+        const { args, flags } = await this.parse(TicketsMessages);
+        // Positional and flag are alternatives — `tickets get <n>` and
+        // `tickets update <n>` set the positional convention, the flag
+        // predates it and stays supported.
+        const ticketNumber = args.ticketNumber ?? flags.ticket;
+        if (ticketNumber === undefined) {
+            throw new UsageError('Missing ticket number. Pass it positionally (`tickets messages <number>`) or via --ticket.');
+        }
+        if (args.ticketNumber !== undefined && flags.ticket !== undefined) {
+            throw new UsageError('Pass the ticket number either positionally or via --ticket, not both.');
+        }
+        const client = this.apiClient(flags);
+        const agentId = await this.agentId(flags, client);
+        const extraQuery = {};
+        if (flags.types)
+            extraQuery.types = flags.types;
+        if (flags.order)
+            extraQuery.order = flags.order;
+        const { pages, items } = await fetchPages((query) => client.GET('/agents/{agentId}/helpdesk/tickets/{ticketNumber}/messages', {
+            params: {
+                path: {
+                    agentId,
+                    ticketNumber
+                },
+                query: { ...query, ...extraQuery }
+            }
+        }), { limit: flags.limit, cursor: flags.cursor, all: flags.all });
+        const rows = items.map((m) => ({
+            id: String(m.id ?? ''),
+            type: String(m.type ?? ''),
+            sender: senderLabel(m.sender),
+            content: String(m.contentText ?? m.content ?? ''),
+            createdAt: String(m.createdAt ?? '')
+        }));
+        const last = pages.at(-1);
+        // --json must stay the raw API shape even when --all merges pages
+        const raw = pages.length === 1
+            ? pages[0]
+            : { data: items, pagination: last?.pagination };
+        this.printData(flags, raw, rows, COLUMNS);
+        if (!flags.all && last?.pagination.hasMore && last.pagination.cursor) {
+            this.note(flags, `More results: rerun with --cursor ${last.pagination.cursor} (or use --all)`);
+        }
+    }
+}

package/dist/commands/tickets/reply.js

@@ -0,0 +1,66 @@
+import { Args, Flags } from '@oclif/core';
+import { AgentCommand } from '../../base/agent-command.js';
+import { throwIfError } from '../../client/client.js';
+import { UsageError } from '../../errors/errors.js';
+export default class TicketsReply extends AgentCommand {
+    static description = "Post an agent reply to a ticket's message thread";
+    static examples = [
+        '<%= config.bin %> tickets reply 42 -m "On it" --author-email sam@example.com -a agt_123'
+    ];
+    static args = {
+        ticketNumber: Args.integer({
+            required: false,
+            description: 'Ticket number (alternative to --ticket)'
+        })
+    };
+    static flags = {
+        ...AgentCommand.baseFlags,
+        ticket: Flags.integer({
+            description: 'Ticket number'
+        }),
+        message: Flags.string({
+            char: 'm',
+            required: true,
+            description: 'Reply body as GitHub-flavored Markdown'
+        }),
+        'author-id': Flags.string({
+            description: 'Platform user id of the team member the reply is attributed to (exactly one of --author-id/--author-email)',
+            exactlyOne: ['author-id', 'author-email']
+        }),
+        'author-email': Flags.string({
+            description: 'Email of the team member the reply is attributed to (exactly one of --author-id/--author-email)',
+            exactlyOne: ['author-id', 'author-email']
+        })
+    };
+    async run() {
+        const { args, flags } = await this.parse(TicketsReply);
+        // Positional and flag are alternatives — `tickets get <n>` and
+        // `tickets update <n>` set the positional convention, the flag
+        // predates it and stays supported.
+        const ticketNumber = args.ticketNumber ?? flags.ticket;
+        if (ticketNumber === undefined) {
+            throw new UsageError('Missing ticket number. Pass it positionally (`tickets reply <number>`) or via --ticket.');
+        }
+        if (args.ticketNumber !== undefined && flags.ticket !== undefined) {
+            throw new UsageError('Pass the ticket number either positionally or via --ticket, not both.');
+        }
+        const client = this.apiClient(flags);
+        const agentId = await this.agentId(flags, client);
+        const body = {
+            type: 'reply',
+            content: flags.message,
+            ...(flags['author-id'] ? { authorId: flags['author-id'] } : {}),
+            ...(flags['author-email']
+                ? { authorEmail: flags['author-email'] }
+                : {})
+        };
+        const { error, response } = await client.POST('/agents/{agentId}/helpdesk/tickets/{ticketNumber}/messages', {
+            params: {
+                path: { agentId, ticketNumber }
+            },
+            body
+        });
+        throwIfError(response, error);
+        this.success(flags, `Reply posted to ticket ${ticketNumber}`);
+    }
+}

package/dist/commands/tickets/search.js

@@ -0,0 +1,53 @@
+import { Args, Flags } from '@oclif/core';
+import { AgentCommand } from '../../base/agent-command.js';
+import { throwIfError } from '../../client/client.js';
+const COLUMNS = [
+    { key: 'ticketNumber', header: 'TICKET' },
+    { key: 'subject', header: 'SUBJECT' },
+    { key: 'statusCategory', header: 'STATUS' },
+    { key: 'channel', header: 'CHANNEL' },
+    { key: 'createdAt', header: 'CREATED' }
+];
+export default class TicketsSearch extends AgentCommand {
+    static description = 'Search tickets by message content';
+    static examples = [
+        '<%= config.bin %> tickets search "refund not received" -a agt_123',
+        '<%= config.bin %> tickets search "refund" -a agt_123 --limit 10 --json'
+    ];
+    static args = {
+        query: Args.string({
+            required: true,
+            description: 'Free-text search terms (matched against ticket messages)'
+        })
+    };
+    static flags = {
+        ...AgentCommand.baseFlags,
+        limit: Flags.integer({
+            description: 'Number of results (1–50, default 20)',
+            min: 1,
+            max: 50
+        })
+    };
+    async run() {
+        const { args, flags } = await this.parse(TicketsSearch);
+        const client = this.apiClient(flags);
+        const agentId = await this.agentId(flags, client);
+        const { data, error, response } = await client.POST('/agents/{agentId}/helpdesk/tickets/search', {
+            params: { path: { agentId } },
+            body: {
+                query: args.query,
+                limit: flags.limit ?? 20
+            }
+        });
+        throwIfError(response, error);
+        const result = data;
+        const rows = result.data.map((t) => ({
+            ticketNumber: String(t.ticketNumber ?? ''),
+            subject: String(t.subject ?? ''),
+            statusCategory: String(t.statusCategory ?? ''),
+            channel: String(t.channel ?? ''),
+            createdAt: String(t.createdAt ?? '')
+        }));
+        this.printData(flags, data, rows, COLUMNS);
+    }
+}

package/dist/commands/tickets/update.js

@@ -0,0 +1,38 @@
+import { Args, Flags } from '@oclif/core';
+import { AgentCommand } from '../../base/agent-command.js';
+import { bodyFieldFlags } from '../../base/base-command.js';
+import { readBodyData } from '../../base/body-input.js';
+import { throwIfError } from '../../client/client.js';
+export default class TicketsUpdate extends AgentCommand {
+    static description = "Update a ticket's status, assignee, and/or team";
+    static examples = [
+        '<%= config.bin %> tickets update 42 --data \'{"statusCategory":"closed"}\' -a agt_123'
+    ];
+    static args = {
+        ticketNumber: Args.integer({
+            required: true,
+            description: 'Ticket number'
+        })
+    };
+    static flags = {
+        ...AgentCommand.baseFlags,
+        ...bodyFieldFlags,
+        data: Flags.string({
+            description: 'JSON body (@file, @-, or inline). Fields: statusId, statusCategory, assigneeId, assigneeEmail, teamId'
+        })
+    };
+    async run() {
+        const { args, flags } = await this.parse(TicketsUpdate);
+        const body = await readBodyData(flags.data, flags.field);
+        const client = this.apiClient(flags);
+        const agentId = await this.agentId(flags, client);
+        const { error, response } = await client.PATCH('/agents/{agentId}/helpdesk/tickets/{ticketNumber}', {
+            params: {
+                path: { agentId, ticketNumber: args.ticketNumber }
+            },
+            body: body
+        });
+        throwIfError(response, error);
+        this.success(flags, `Updated ticket ${args.ticketNumber}`);
+    }
+}

package/dist/commands/whatsapp/send-template.js

@@ -0,0 +1,94 @@
+import { Args, Flags } from '@oclif/core';
+import { AgentCommand } from '../../base/agent-command.js';
+import { readTextInput } from '../../base/body-input.js';
+import { throwIfError } from '../../client/client.js';
+import { UsageError } from '../../errors/errors.js';
+/** Parse --variables: a JSON object grouped by component, the exact shape
+ * `whatsapp templates` reports per template. Leaf validation is the API's
+ * job — it returns field-level errors for bad keys or non-string values. */
+async function parseVariables(value) {
+    const raw = await readTextInput(value, '--variables');
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    }
+    catch {
+        throw new UsageError('--variables must be valid JSON (inline, @file, or @-).');
+    }
+    if (typeof parsed !== 'object' ||
+        parsed === null ||
+        Array.isArray(parsed)) {
+        throw new UsageError('--variables must be a JSON object grouped by component, e.g. \'{"body":{"1":"Jane"}}\'.');
+    }
+    return parsed;
+}
+export default class WhatsappSendTemplate extends AgentCommand {
+    static summary = 'Send an approved WhatsApp template message';
+    static description = 'Send an approved WhatsApp template to a phone number from one of the ' +
+        'agent’s connected numbers. No user ID is needed — a Chatbase user is ' +
+        'resolved or created from the recipient number, and replies flow ' +
+        'through the agent’s regular WhatsApp pipeline. Use `whatsapp ' +
+        'templates` to see available templates and the variables each expects.';
+    static examples = [
+        '<%= config.bin %> whatsapp send-template order_update --to 14155552671 -a agt_123',
+        '<%= config.bin %> whatsapp send-template order_update --to 14155552671 --language en_US --variables \'{"header":{"1":"#1042"},"body":{"1":"Jane","2":"Friday"}}\' -a agt_123'
+    ];
+    static args = {
+        template: Args.string({
+            required: true,
+            description: 'Name of the approved template'
+        })
+    };
+    static flags = {
+        ...AgentCommand.baseFlags,
+        to: Flags.string({
+            required: true,
+            description: 'Recipient phone number in international format (digits with country code)'
+        }),
+        from: Flags.string({
+            description: 'Which connected WhatsApp number to send from — optional when the agent has exactly one'
+        }),
+        language: Flags.string({
+            description: 'Template language code (e.g. en_US) — optional when the template exists in a single language'
+        }),
+        variables: Flags.string({
+            description: 'Template variable values as JSON grouped by component (@file, @-, or inline), e.g. \'{"body":{"1":"Jane"}}\''
+        })
+    };
+    async run() {
+        const { args, flags } = await this.parse(WhatsappSendTemplate);
+        const variables = flags.variables
+            ? await parseVariables(flags.variables)
+            : undefined;
+        const client = this.apiClient(flags);
+        const agentId = await this.agentId(flags, client);
+        const body = {
+            to: flags.to,
+            ...(flags.from ? { from: flags.from } : {}),
+            template: {
+                name: args.template,
+                ...(flags.language ? { language: flags.language } : {}),
+                // The spec defaults variables to {} and the generated type
+                // makes it required — send the default explicitly.
+                variables: variables ?? {}
+            }
+        };
+        const { data, error, response } = await client.POST('/agents/{agentId}/whatsapp/messages/template', {
+            params: { path: { agentId } },
+            body
+        });
+        throwIfError(response, error);
+        const sent = data;
+        if (flags.json) {
+            process.stdout.write(`${JSON.stringify(sent, null, 2)}\n`);
+            return;
+        }
+        this.success(flags, `Sent template "${args.template}" to ${sent.to}`);
+        if (sent.conversationId) {
+            this.note(flags, `Conversation: ${sent.conversationId}`);
+        }
+        if (sent.messageId) {
+            process.stdout.write(`${sent.messageId}\n`);
+        }
+    }
+}

package/dist/commands/whatsapp/templates.js

@@ -0,0 +1,55 @@
+import { AgentCommand } from '../../base/agent-command.js';
+import { throwIfError } from '../../client/client.js';
+const COLUMNS = [
+    { key: 'name', header: 'NAME' },
+    { key: 'language', header: 'LANGUAGE' },
+    { key: 'category', header: 'CATEGORY' },
+    { key: 'format', header: 'FORMAT' },
+    { key: 'wabaId', header: 'WABA' },
+    { key: 'variables', header: 'VARIABLES' }
+];
+/** {header: ["1"], body: ["1","2"]} → "header:1 body:1,2" — the keys a send
+ * must supply, in the grouping `send-template --variables` expects. */
+function variablesSummary(variables) {
+    return Object.entries(variables)
+        .map(([component, keys]) => `${component}:${keys.join(',')}`)
+        .join(' ');
+}
+export default class WhatsappTemplates extends AgentCommand {
+    static summary = 'List approved WhatsApp templates for an agent';
+    static description = 'List the approved WhatsApp templates available to the agent, across ' +
+        'all of its connected WhatsApp Business Accounts. A template can only ' +
+        'be sent from a number on its own Business Account — pick a sender ' +
+        'whose WABA matches the template’s WABA column.';
+    static examples = [
+        '<%= config.bin %> whatsapp templates -a agt_123',
+        '<%= config.bin %> whatsapp templates -a agt_123 --json'
+    ];
+    static flags = { ...AgentCommand.baseFlags };
+    async run() {
+        const { flags } = await this.parse(WhatsappTemplates);
+        const client = this.apiClient(flags);
+        const agentId = await this.agentId(flags, client);
+        const { data, error, response } = await client.GET('/agents/{agentId}/whatsapp/templates', { params: { path: { agentId } } });
+        throwIfError(response, error);
+        const result = data;
+        const rows = result.templates.map((t) => ({
+            name: t.name,
+            language: t.language,
+            category: t.category,
+            format: t.parameterFormat,
+            wabaId: t.wabaId,
+            variables: variablesSummary(t.variables)
+        }));
+        this.printData(flags, result, rows, COLUMNS);
+        if (result.senders.length > 0) {
+            const senders = result.senders
+                .map((s) => `${s.from}${s.verifiedName ? ` (${s.verifiedName})` : ''} — waba ${s.wabaId}`)
+                .join('; ');
+            this.note(flags, `Senders: ${senders}`);
+        }
+        if (!result.complete) {
+            this.note(flags, `Warning: partial list — could not read WABA(s): ${result.unavailableWabaIds.join(', ')}. Retry to pick them up.`);
+        }
+    }
+}

package/dist/config/paths.js

@@ -0,0 +1,22 @@
+/**
+ * Every path the CLI touches on disk, per the XDG Base Directory spec —
+ * config (user-created, not regenerable), state/logs (machine-generated
+ * history), cache (disposable — cleanup tools may purge it anytime).
+ * These three directories are the CLI's ENTIRE disk footprint; the README's
+ * uninstall instructions promise exactly them, so never write anywhere else.
+ *
+ * Deliberate choices: XDG applies on macOS too (matching `gh`, not
+ * ~/Library), and these are functions rather than constants because the
+ * env overrides must be read at call time — tests stub XDG_* per test.
+ */
+import os from 'node:os';
+import path from 'node:path';
+function xdg(envVar, fallback) {
+    const v = process.env[envVar];
+    return v && v.length > 0 ? v : path.join(os.homedir(), fallback);
+}
+export const configDir = () => path.join(xdg('XDG_CONFIG_HOME', '.config'), 'chatbase');
+export const configFile = () => path.join(configDir(), 'config.json');
+export const stateDir = () => path.join(xdg('XDG_STATE_HOME', '.local/state'), 'chatbase');
+export const logsDir = () => path.join(stateDir(), 'logs');
+export const cacheDir = () => path.join(xdg('XDG_CACHE_HOME', '.cache'), 'chatbase');

package/dist/config/resolve.js

@@ -0,0 +1,37 @@
+import { readUserConfig } from './store.js';
+export function resolveApiKey() {
+    const env = process.env.CHATBASE_API_KEY;
+    if (env && env.length > 0)
+        return { value: env, source: 'CHATBASE_API_KEY' };
+    const stored = readUserConfig().apiKey;
+    if (stored)
+        return { value: stored, source: 'user config' };
+    return undefined;
+}
+export function resolveAgent(flag) {
+    if (flag)
+        return { value: flag, source: 'flag' };
+    const env = process.env.CHATBASE_AGENT_ID;
+    if (env && env.length > 0)
+        return { value: env, source: 'CHATBASE_AGENT_ID' };
+    const stored = readUserConfig().agent;
+    if (stored)
+        return { value: stored, source: 'user config' };
+    return undefined;
+}
+export function resolveTimeoutMs() {
+    const env = process.env.CHATBASE_TIMEOUT;
+    if (env && /^\d+$/.test(env))
+        return Number(env);
+    return readUserConfig().timeoutMs ?? 30000;
+}
+/** Where resolveTimeoutMs()'s value came from — split out for `config get/list`,
+ * which need to name the source without duplicating the precedence logic above. */
+export function resolveTimeoutSource() {
+    const env = process.env.CHATBASE_TIMEOUT;
+    if (env && /^\d+$/.test(env))
+        return 'CHATBASE_TIMEOUT';
+    if (readUserConfig().timeoutMs !== undefined)
+        return 'user config';
+    return 'default';
+}