@eightstate/escli 0.5.0 → 0.7.0

package/dist/commands/notion/db/query.js

@@ -0,0 +1,451 @@
+import { Args, Flags } from '@oclif/core';
+import { readFile } from 'node:fs/promises';
+import { z } from 'zod';
+import { ErrorCode } from '@eightstate/contracts/errors';
+import { ExitCodes } from '@eightstate/contracts/exit-codes';
+import { BaseCommand } from '../../../base-command.js';
+import { EscliError } from '../../../lib/escli-error.js';
+import { renderTable } from '../../../io/render-table.js';
+import { renderTrailer } from '../../../io/render-trailer.js';
+import { isPlainOutput, writeStdout, writeStderr } from '../../../io/io.js';
+import { NOTION_VERSION, notionDataSourceQuery } from '../../../services/notion.js';
+import { hasManifestFlag } from '../../../lib/notion/manifest-pass.js';
+const SortDirectionSchema = z.enum(['ascending', 'descending']);
+const SortSchema = z.object({ property: z.string(), direction: SortDirectionSchema });
+const DbQueryRowSchema = z.object({
+    id: z.string(),
+    title: z.string().optional(),
+    properties: z.record(z.string(), z.unknown()).default({}),
+});
+const DbQueryDataSchema = z.object({
+    source: z.object({
+        database_id: z.string().optional(),
+        data_source_id: z.string(),
+        name: z.string().optional(),
+    }),
+    query: z.object({
+        filter: z.string().optional(),
+        sorts: z.array(SortSchema).default([]),
+        selected_properties: z.array(z.string()).default([]),
+    }),
+    rows: z.array(DbQueryRowSchema),
+    has_more: z.boolean(),
+    next: z.string().nullable(),
+    page_size: z.number().int().optional(),
+    start_index: z.number().int().optional(),
+    more_count: z.number().int().nullable().optional(),
+    request_status: z.unknown().optional(),
+    warnings: z.array(z.string()).optional(),
+});
+export default class NotionDbQuery extends BaseCommand {
+    static errors = [
+        ErrorCode.UsageRequired,
+        ErrorCode.UsageInvalid,
+        ErrorCode.UsageUnknownFlag,
+        ErrorCode.JsonInvalid,
+        ErrorCode.AuthRequired,
+        ErrorCode.NotionEnrollmentRequired,
+        ErrorCode.NotionUnauthorized,
+        ErrorCode.NotionRestricted,
+        ErrorCode.NotionNotFound,
+        ErrorCode.NotionValidation,
+        ErrorCode.NotionRateLimited,
+        ErrorCode.GateInvalidResponse,
+        ErrorCode.NetworkError,
+        ErrorCode.NetworkTimeout,
+        ErrorCode.ServiceUnavailable,
+    ];
+    static summary = 'Query a Notion data source';
+    static description = 'Read rows from a Notion data source with pass-through filters, sorts, selected properties, and stateless pagination.';
+    static examples = [
+        '<%= config.bin %> notion db query ds_362ef7b0c9a44f0aa0b3d174fd12004a --select Name,Status,Due',
+        '<%= config.bin %> notion db query ds_362ef7b0c9a44f0aa0b3d174fd12004a --filter \'{"property":"Status","status":{"equals":"In Progress"}}\' --sort Due:asc',
+        '<%= config.bin %> notion db query ds_362ef7b0c9a44f0aa0b3d174fd12004a --next eyJzZXNzaW9uIjoiNGNmNyJ9',
+    ];
+    static aliases = ['notion database query', 'notion ds query'];
+    static flags = {
+        filter: Flags.string({ description: 'Notion filter object as JSON or @file.' }),
+        sort: Flags.string({ description: 'Repeatable sort shorthand: prop:asc or prop:desc.', multiple: true, exclusive: ['sort-json'] }),
+        'sort-json': Flags.string({ description: 'Exact Notion sorts array as JSON or @file.', exclusive: ['sort'] }),
+        source: Flags.string({ description: 'Select a data source when the target is a multi-source database.' }),
+        'result-type': Flags.option({ description: 'Wiki-only result-type filter.', options: ['page', 'data_source', 'any'], default: 'page' })(),
+        select: Flags.string({ description: 'Comma-separated properties to display.' }),
+        'page-size': Flags.integer({ description: 'Rows to request, 1-100.' }),
+        'title-prop': Flags.string({ description: 'Override title property detection.' }),
+        next: Flags.string({ description: 'Continue from Notion pagination token.' }),
+        raw: Flags.boolean({ description: 'Return verbatim Notion response body.' }),
+    };
+    static args = {
+        target: Args.string({ description: 'Notion data-source UUID, database UUID, or Notion URL.', required: true }),
+    };
+    static enableJsonFlag = true;
+    static strict = true;
+    async run() {
+        if (hasManifestFlag(this.argv)) {
+            await super.run();
+            return;
+        }
+        const start = Date.now();
+        let json = false;
+        try {
+            const { args, flags } = await this.parse(NotionDbQuery);
+            const queryFlags = flags;
+            json = Boolean(queryFlags.json);
+            const pageSize = queryFlags['page-size'] ?? defaultPageSize();
+            if (pageSize < 1 || pageSize > 100) {
+                throw new EscliError('notion db query: --page-size max is 100 for Notion data source queries.', {
+                    code: ErrorCode.UsageInvalid,
+                    exitCode: ExitCodes.Usage,
+                });
+            }
+            const selectedProperties = parseSelect(queryFlags.select);
+            const filter = await parseJsonFlag(queryFlags.filter, '--filter');
+            validateTimestampFilter(filter);
+            const sorts = await parseSorts(queryFlags);
+            const dataSourceId = parseDataSourceTarget(args.target);
+            const result = await notionDataSourceQuery(dataSourceId, filter, sorts.length > 0 ? sorts : undefined, pageSize, queryFlags.next);
+            if (queryFlags.raw) {
+                await writeStdout(`${JSON.stringify(result.raw)}\n`);
+                return;
+            }
+            const data = shapeData(result, { dataSourceId, filter, sorts, selectedProperties, pageSize, titleProp: queryFlags['title-prop'] });
+            if (json)
+                await emitSuccessEnvelope(this.id ?? 'notion db query', this.config.version, data, Date.now() - start);
+            else
+                await writeStdout(`${renderDbQuery(data)}\n`);
+        }
+        catch (error) {
+            await emitErrorEnvelope(this.id ?? 'notion db query', this.config.version, toEscliError(error), Date.now() - start, json);
+        }
+    }
+    async execute() {
+        throw new Error('run handles notion db query');
+    }
+}
+function notionEnvelopeMeta(command, version, durationMs, next) {
+    return {
+        schema_version: '1',
+        escli_version: version,
+        command,
+        warnings: [],
+        duration_ms: durationMs,
+        next,
+        notion_version: NOTION_VERSION,
+    };
+}
+async function emitSuccessEnvelope(command, version, data, durationMs) {
+    await writeStdout(`${JSON.stringify({ ok: true, data, error: null, meta: notionEnvelopeMeta(command, version, durationMs, data.next) })}\n`);
+}
+async function emitErrorEnvelope(command, version, error, durationMs, json) {
+    process.exitCode = error.exitCode;
+    if (json) {
+        await writeStdout(`${JSON.stringify({
+            ok: false,
+            data: null,
+            error: {
+                code: error.code,
+                message: error.message,
+                remediation: error.remediation,
+                details: error.details,
+                cause_code: error.causeCode,
+            },
+            meta: notionEnvelopeMeta(command, version, durationMs, null),
+        })}\n`);
+        return;
+    }
+    await writeStderr(`${error.message}\n`);
+}
+function toEscliError(error) {
+    if (error instanceof EscliError)
+        return error;
+    if (error instanceof z.ZodError) {
+        return new EscliError('input validation failed', { code: ErrorCode.ValidationFailed, exitCode: ExitCodes.Usage, details: error.issues });
+    }
+    if (error instanceof Error)
+        return new EscliError(error.message, { code: ErrorCode.Internal });
+    return new EscliError('unknown error', { code: ErrorCode.Unknown, details: error });
+}
+function defaultPageSize() {
+    return isPlainOutput() ? 25 : 10;
+}
+async function parseJsonFlag(value, flagName) {
+    if (!value)
+        return undefined;
+    const text = value.startsWith('@') ? await readFile(value.slice(1), 'utf8') : value;
+    try {
+        return JSON.parse(text);
+    }
+    catch (error) {
+        throw new EscliError(`notion db query: ${flagName} is not valid JSON: ${error instanceof Error ? error.message : String(error)}`, {
+            code: ErrorCode.JsonInvalid,
+            exitCode: ExitCodes.Usage,
+        });
+    }
+}
+async function parseSorts(flags) {
+    if (flags['sort-json']) {
+        const parsed = await parseJsonFlag(flags['sort-json'], '--sort-json');
+        const result = z.array(SortSchema).safeParse(parsed);
+        if (!result.success) {
+            throw new EscliError('notion db query: --sort-json must be a Notion sorts array.', {
+                code: ErrorCode.UsageInvalid,
+                exitCode: ExitCodes.Usage,
+                details: result.error.issues,
+            });
+        }
+        return result.data;
+    }
+    return (flags.sort ?? []).map((value) => {
+        const separator = value.lastIndexOf(':');
+        const property = separator > 0 ? value.slice(0, separator).trim() : '';
+        const direction = separator > 0 ? value.slice(separator + 1).trim().toLowerCase() : '';
+        if (!property || !['asc', 'desc'].includes(direction)) {
+            throw new EscliError(`notion db query: malformed --sort ${value}; use prop:asc or prop:desc.`, {
+                code: ErrorCode.UsageInvalid,
+                exitCode: ExitCodes.Usage,
+            });
+        }
+        return { property, direction: direction === 'asc' ? 'ascending' : 'descending' };
+    });
+}
+function parseSelect(value) {
+    return value?.split(',').map((part) => part.trim()).filter(Boolean) ?? [];
+}
+function validateTimestampFilter(filter) {
+    if (!filter || typeof filter !== 'object' || Array.isArray(filter))
+        return;
+    const record = filter;
+    if (typeof record.timestamp === 'string' && typeof record.property === 'string') {
+        throw new EscliError('notion db query: timestamp filters must not include property. Use {"timestamp":"created_time","created_time":{...}}.', {
+            code: ErrorCode.UsageInvalid,
+            exitCode: ExitCodes.Usage,
+        });
+    }
+}
+function parseDataSourceTarget(target) {
+    const normalized = target.trim();
+    if (!normalized)
+        throwInvalidTarget(target);
+    const fromUrl = extractNotionIdFromUrl(normalized);
+    const candidate = fromUrl ?? normalized;
+    const compact = candidate.replaceAll('-', '');
+    if (/^(ds_)?[0-9a-f]{32}$/iu.test(compact))
+        return candidate;
+    if (/^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/iu.test(candidate))
+        return candidate;
+    if (/^ds_[A-Za-z0-9_-]+$/u.test(candidate))
+        return candidate;
+    throwInvalidTarget(target);
+}
+function extractNotionIdFromUrl(value) {
+    let url;
+    try {
+        url = new URL(value);
+    }
+    catch {
+        return undefined;
+    }
+    const sourceParam = url.searchParams.get('source') ?? url.searchParams.get('data_source_id') ?? url.searchParams.get('dataSourceId');
+    if (sourceParam)
+        return sourceParam;
+    const match = /([0-9a-f]{32})(?:[/?#-]|$)/iu.exec(url.pathname);
+    return match?.[1];
+}
+function throwInvalidTarget(target) {
+    throw new EscliError(`notion db query: not a Notion database/data-source ID or URL: ${target}`, {
+        code: ErrorCode.UsageInvalid,
+        exitCode: ExitCodes.Error,
+    });
+}
+function shapeData(result, context) {
+    const list = asQueryList(result.data);
+    const rows = (list.results ?? []).map((item) => shapeRow(item, context.titleProp));
+    return DbQueryDataSchema.parse({
+        source: {
+            database_id: extractDatabaseId(list.results),
+            data_source_id: context.dataSourceId,
+            name: extractSourceName(result.data),
+        },
+        query: {
+            filter: summarizeFilter(context.filter),
+            sorts: context.sorts,
+            selected_properties: context.selectedProperties.length > 0 ? context.selectedProperties : inferSelectedProperties(rows),
+        },
+        rows,
+        has_more: Boolean(list.has_more ?? result.meta.next),
+        next: result.meta.next,
+        page_size: context.pageSize,
+        start_index: undefined,
+        more_count: undefined,
+        request_status: list.request_status,
+        warnings: warningsFor(list),
+    });
+}
+function asQueryList(value) {
+    if (!value || typeof value !== 'object' || Array.isArray(value))
+        return {};
+    return value;
+}
+function shapeRow(value, titleProp) {
+    const record = recordValue(value) ?? {};
+    const properties = recordValue(record.properties) ?? {};
+    const title = extractTitle(properties, titleProp) ?? stringValue(record.title) ?? stringValue(record.name) ?? '';
+    return {
+        id: stringValue(record.id) ?? '',
+        title,
+        properties: Object.fromEntries(Object.entries(properties).map(([key, property]) => [key, plainPropertyValue(property)])),
+    };
+}
+function extractTitle(properties, titleProp) {
+    if (titleProp && properties[titleProp] !== undefined)
+        return stringifyValue(plainPropertyValue(properties[titleProp]));
+    for (const [key, value] of Object.entries(properties)) {
+        const record = recordValue(value);
+        if (record?.type === 'title' || key.toLowerCase() === 'name')
+            return stringifyValue(plainPropertyValue(value));
+    }
+    return undefined;
+}
+function plainPropertyValue(property) {
+    const record = recordValue(property);
+    if (!record)
+        return property;
+    const type = stringValue(record.type);
+    if (type && record[type] !== undefined)
+        return plainTypedValue(record[type]);
+    return property;
+}
+function plainTypedValue(value) {
+    if (Array.isArray(value))
+        return value.map((item) => stringifyValue(plainTypedValue(item))).filter(Boolean).join(', ');
+    const record = recordValue(value);
+    if (!record)
+        return value;
+    if (typeof record.plain_text === 'string')
+        return record.plain_text;
+    if (typeof record.name === 'string')
+        return record.name;
+    if (typeof record.start === 'string')
+        return record.end ? `${record.start} → ${String(record.end)}` : record.start;
+    if (typeof record.number === 'number')
+        return record.number;
+    if (typeof record.checkbox === 'boolean')
+        return record.checkbox;
+    if (typeof record.email === 'string')
+        return record.email;
+    if (typeof record.phone_number === 'string')
+        return record.phone_number;
+    if (typeof record.url === 'string')
+        return record.url;
+    if (typeof record.content === 'string')
+        return record.content;
+    return JSON.stringify(record);
+}
+function renderDbQuery(data) {
+    const lines = [
+        `${data.source.name ? `${data.source.name} — ` : ''}data_source ${shortId(data.source.data_source_id)}`,
+        `query: ${data.query.filter ?? 'all'}${data.query.sorts.length > 0 ? ` · sort ${renderSortSummary(data.query.sorts)}` : ''}${data.query.selected_properties.length > 0 ? ` · props ${data.query.selected_properties.join(',')}` : ''}`,
+        `returned: ${data.rows.length} · page_size ${data.page_size ?? data.rows.length} · more ${data.has_more ? 'yes' : 'no'}`,
+        '',
+    ];
+    if (data.warnings && data.warnings.length > 0)
+        lines.push(...data.warnings.map((warning) => `warning: ${warning}`), '');
+    if (data.rows.length === 0)
+        lines.push('No matching rows.');
+    else
+        lines.push(renderRowsTable(data));
+    const trailer = renderTrailer({ next: data.next, remaining: data.more_count });
+    if (trailer)
+        lines.push('', trailer);
+    return lines.join('\n');
+}
+function renderRowsTable(data) {
+    const selected = data.query.selected_properties.length > 0 ? data.query.selected_properties : inferSelectedProperties(data.rows);
+    const titleHeader = selected[0] ?? 'Name';
+    const propertyHeaders = selected.slice(1);
+    const header = ['#', 'id', titleHeader, ...propertyHeaders];
+    const start = data.start_index ?? 1;
+    const rows = data.rows.map((row, index) => [
+        start + index,
+        shortId(row.id),
+        row.title ?? '',
+        ...propertyHeaders.map((property) => stringifyValue(row.properties[property])),
+    ]);
+    return renderTable({ header, rows });
+}
+function inferSelectedProperties(rows) {
+    const keys = new Set();
+    for (const row of rows) {
+        for (const key of Object.keys(row.properties))
+            keys.add(key);
+    }
+    return [...keys];
+}
+function renderSortSummary(sorts) {
+    return sorts.map((sort) => `${sort.property} ${sort.direction === 'ascending' ? '↑' : '↓'}`).join(', ');
+}
+function summarizeFilter(filter) {
+    if (filter === undefined)
+        return undefined;
+    const record = recordValue(filter);
+    if (!record)
+        return JSON.stringify(filter);
+    const property = stringValue(record.property) ?? stringValue(record.timestamp);
+    if (!property)
+        return JSON.stringify(filter);
+    const condition = Object.entries(record).find(([key]) => key !== 'property' && key !== 'timestamp');
+    const conditionRecord = recordValue(condition?.[1]);
+    if (!condition || !conditionRecord)
+        return JSON.stringify(filter);
+    const [operator, operand] = Object.entries(conditionRecord)[0] ?? [];
+    if (!operator)
+        return JSON.stringify(filter);
+    const renderedOperand = Array.isArray(operand) ? `[${operand.map(String).join(', ')}]` : stringifyValue(operand);
+    return `${property} ${operator.replaceAll('_', ' ')} ${renderedOperand}`;
+}
+function extractDatabaseId(results) {
+    for (const result of results ?? []) {
+        const parent = recordValue(recordValue(result)?.parent);
+        const databaseId = stringValue(parent?.database_id);
+        if (databaseId)
+            return databaseId;
+    }
+    return undefined;
+}
+function extractSourceName(value) {
+    const record = recordValue(value);
+    return stringValue(record?.source_name) ?? stringValue(record?.name) ?? stringValue(recordValue(record?.data_source)?.name);
+}
+function warningsFor(list) {
+    const status = recordValue(list.request_status);
+    if (status?.type === 'incomplete')
+        return ['query may be incomplete; narrow with date/status filters for complete coverage.'];
+    return undefined;
+}
+function shortId(value) {
+    if (value.length <= 13)
+        return value;
+    const compact = value.replaceAll('-', '');
+    if (compact.length >= 12)
+        return `${compact.slice(0, 7)}…${compact.slice(-4)}`;
+    return value;
+}
+function stringifyValue(value) {
+    if (value === null || value === undefined)
+        return '';
+    if (typeof value === 'string')
+        return value;
+    if (typeof value === 'number' || typeof value === 'boolean')
+        return String(value);
+    if (Array.isArray(value))
+        return value.map((item) => stringifyValue(item)).filter(Boolean).join(', ');
+    return JSON.stringify(value);
+}
+function recordValue(value) {
+    return value && typeof value === 'object' && !Array.isArray(value) ? value : undefined;
+}
+function stringValue(value) {
+    return typeof value === 'string' && value.length > 0 ? value : undefined;
+}
+export { DbQueryDataSchema, renderDbQuery, parseDataSourceTarget, parseSelect, parseSorts, summarizeFilter, NOTION_VERSION };
+//# sourceMappingURL=query.js.map

package/dist/commands/notion/db/row/create.js

@@ -0,0 +1,74 @@
+import { Args, Flags } from '@oclif/core';
+import { hasManifestFlag } from '../../../../lib/notion/manifest-pass.js';
+import { z } from 'zod';
+import { ErrorCode } from '@eightstate/contracts/errors';
+import { BaseCommand } from '../../../../base-command.js';
+import { writeStdout } from '../../../../io/io.js';
+import { notionPagesCreate } from '../../../../services/notion.js';
+import { dbWriteErrors, emitErrorEnvelope, emitSuccessEnvelope, normalizeCreate, rawOutput, readJsonObjectInput, renderCreate, stripCommandFields, toEscliError, } from '../../../../lib/notion/db-row/common.js';
+export const NotionDbRowCreateDataSchema = z.object({
+    action: z.literal('created'),
+    page: z.object({ id: z.string(), title: z.string(), url: z.string() }),
+    parent: z.object({ data_source_id: z.string(), database_id: z.string().nullable() }),
+    written: z.record(z.string(), z.unknown()),
+    bot: z.string(),
+    last_edited_time: z.string(),
+}).passthrough();
+export default class NotionDbRowCreate extends BaseCommand {
+    static errors = dbWriteErrors;
+    static summary = 'Create a Notion data-source row';
+    static description = 'Create one new page/row in a Notion data source with typed properties.';
+    static examples = [
+        '<%= config.bin %> notion db row create 248104cd-477e-80af-bc30-000bd28de8f9 --properties \'{"Name":{"title":[{"text":{"content":"Launch checklist"}}]}}\'',
+        '<%= config.bin %> notion db row create 248104cd-477e-80af-bc30-000bd28de8f9 --properties @row.json --json',
+        '<%= config.bin %> notion db row create 248104cd-477e-80af-bc30-000bd28de8f9 --properties @row.json --raw',
+    ];
+    static aliases = ['notion db create row', 'notion ds row create'];
+    static flags = {
+        properties: Flags.string({ description: 'Typed Notion properties as JSON, @file, or - for stdin.', required: true }),
+        raw: Flags.boolean({ description: 'Emit verbatim Notion response body.', default: false }),
+    };
+    static args = {
+        data_source_id: Args.string({ description: 'Target Notion data source ID.', required: true }),
+    };
+    static enableJsonFlag = true;
+    static strict = true;
+    async run() {
+        if (hasManifestFlag(this.argv)) {
+            await super.run();
+            return;
+        }
+        const start = Date.now();
+        let json = this.argv.includes('--json');
+        try {
+            const { args, flags } = await this.parse(NotionDbRowCreate);
+            json = Boolean(flags.json);
+            const properties = await readJsonObjectInput(flags.properties, 'properties');
+            const result = await notionPagesCreate({ data_source_id: args.data_source_id }, properties);
+            if (flags.raw) {
+                await writeStdout(`${JSON.stringify(rawOutput(result))}\n`);
+                return;
+            }
+            const data = normalizeCreate(result, properties);
+            const cleanData = stripCommandFields(data);
+            if (json)
+                await emitSuccessEnvelope(this.id ?? 'notion db row create', this.config.version, cleanData, Date.now() - start);
+            else
+                await writeStdout(`${renderCreate(data)}\n`);
+        }
+        catch (error) {
+            await emitErrorEnvelope(this.id ?? 'notion db row create', this.config.version, toEscliError(error), Date.now() - start, json);
+        }
+    }
+    async execute() {
+        const { args, flags } = await this.parse(NotionDbRowCreate);
+        const properties = await readJsonObjectInput(flags.properties, 'properties');
+        const result = await notionPagesCreate({ data_source_id: args.data_source_id }, properties);
+        if (flags.raw)
+            return rawOutput(result);
+        return stripCommandFields(normalizeCreate(result, properties));
+    }
+}
+export { NotionDbRowCreate };
+export { ErrorCode };
+//# sourceMappingURL=create.js.map