@learncard/cli 3.5.1 → 3.6.0

package/src/inbox.test.ts

@@ -0,0 +1,257 @@
+import { describe, expect, it, vi } from 'vitest';
+import { Command } from 'commander';
+import {
+    fetchSentInboxCredentials,
+    filterSince,
+    parseLimit,
+    parseSince,
+    registerInboxCommand,
+    toJsonRecord,
+    type SentInboxRecord,
+} from './inbox';
+
+const baseRecord = (overrides: Partial<SentInboxRecord> = {}): SentInboxRecord => ({
+    id: 'inbox-1',
+    isSigned: true,
+    currentStatus: 'PENDING',
+    expiresAt: '2026-02-01T00:00:00.000Z',
+    createdAt: '2026-01-01T00:00:00.000Z',
+    issuerDid: 'did:example:issuer',
+    ...overrides,
+});
+
+describe('parseLimit', () => {
+    it('defaults to 50', () => {
+        expect(parseLimit(undefined)).toBe(50);
+    });
+
+    it('accepts positive integers', () => {
+        expect(parseLimit('10')).toBe(10);
+    });
+
+    it.each(['abc', '0', '-1', '1.5'])('rejects %s', value => {
+        expect(() => parseLimit(value)).toThrow('--limit');
+    });
+});
+
+describe('parseSince', () => {
+    const now = new Date('2026-01-10T00:00:00.000Z');
+
+    it('parses day durations', () => {
+        expect(parseSince('7d', now).toISOString()).toBe('2026-01-03T00:00:00.000Z');
+    });
+
+    it('parses hour durations', () => {
+        expect(parseSince('24h', now).toISOString()).toBe('2026-01-09T00:00:00.000Z');
+    });
+
+    it('parses minute durations', () => {
+        expect(parseSince('30m', now).toISOString()).toBe('2026-01-09T23:30:00.000Z');
+    });
+
+    it('parses an ISO timestamp', () => {
+        expect(parseSince('2026-01-05T00:00:00.000Z', now).toISOString()).toBe(
+            '2026-01-05T00:00:00.000Z'
+        );
+    });
+
+    it('throws on garbage input', () => {
+        expect(() => parseSince('not-a-duration', now)).toThrow(/Invalid --since/);
+    });
+});
+
+describe('filterSince', () => {
+    it('keeps only records at or after the cutoff', () => {
+        const records = [
+            baseRecord({ id: 'old', createdAt: '2026-01-01T00:00:00.000Z' }),
+            baseRecord({ id: 'new', createdAt: '2026-01-09T00:00:00.000Z' }),
+        ];
+        expect(filterSince(records, new Date('2026-01-05T00:00:00.000Z')).map(r => r.id)).toEqual([
+            'new',
+        ]);
+    });
+
+    it('is a no-op without a cutoff', () => {
+        const records = [baseRecord()];
+        expect(filterSince(records, undefined)).toBe(records);
+    });
+});
+
+describe('inbox command registration', () => {
+    it('does not advertise or accept the unsupported recipient-type filter', async () => {
+        const program = new Command().exitOverride().configureOutput({ writeErr: () => {} });
+        const run = vi.fn();
+        registerInboxCommand(program, run);
+        const list = program.commands[0]!.commands[0]!;
+        expect(list.helpInformation()).not.toContain('--recipient-type');
+        await expect(
+            program.parseAsync(['inbox', 'list', '--recipient-type', 'email'], { from: 'user' })
+        ).rejects.toThrow("unknown option '--recipient-type'");
+        expect(run).not.toHaveBeenCalled();
+    });
+});
+
+describe('fetchSentInboxCredentials', () => {
+    it.each([false, true])(
+        'reports overflow even when server hasMore is %s',
+        async serverHasMore => {
+            const getMySentInboxCredentials = vi.fn().mockResolvedValue({
+                records: [baseRecord({ id: '1' }), baseRecord({ id: '2' })],
+                hasMore: serverHasMore,
+            });
+            const result = await fetchSentInboxCredentials(
+                { getMySentInboxCredentials },
+                { limit: 1 }
+            );
+            expect(result.records.map(record => record.id)).toEqual(['1']);
+            expect(result.hasMore).toBe(true);
+            expect(getMySentInboxCredentials).toHaveBeenCalledExactlyOnceWith({ limit: 1 });
+        }
+    );
+
+    it('requests the last remaining record and stops at an exact limit', async () => {
+        const getMySentInboxCredentials = vi
+            .fn()
+            .mockResolvedValueOnce({ records: [baseRecord()], hasMore: true, cursor: 'next' })
+            .mockResolvedValueOnce({ records: [baseRecord({ id: '2' })], hasMore: false });
+        const result = await fetchSentInboxCredentials({ getMySentInboxCredentials }, { limit: 2 });
+        expect(getMySentInboxCredentials).toHaveBeenNthCalledWith(2, { limit: 1, cursor: 'next' });
+        expect(getMySentInboxCredentials).toHaveBeenCalledTimes(2);
+        expect(result.records).toHaveLength(2);
+        expect(result.hasMore).toBe(false);
+    });
+
+    it('merges cursor-paginated pages up to the requested limit', async () => {
+        const page1 = {
+            hasMore: true,
+            cursor: 'cursor-1',
+            records: [baseRecord({ id: '1' }), baseRecord({ id: '2' })],
+        };
+        const page2 = { hasMore: false, records: [baseRecord({ id: '3' })] };
+        const getMySentInboxCredentials = vi
+            .fn()
+            .mockResolvedValueOnce(page1)
+            .mockResolvedValueOnce(page2);
+
+        const { records, hasMore } = await fetchSentInboxCredentials(
+            { getMySentInboxCredentials },
+            { limit: 10 }
+        );
+
+        expect(records.map(r => r.id)).toEqual(['1', '2', '3']);
+        expect(hasMore).toBe(false);
+        expect(getMySentInboxCredentials).toHaveBeenCalledTimes(2);
+        expect(getMySentInboxCredentials).toHaveBeenNthCalledWith(
+            2,
+            expect.objectContaining({ cursor: 'cursor-1', limit: 8 })
+        );
+    });
+
+    it('stops once the requested limit is reached, reporting more remain', async () => {
+        const page1 = {
+            hasMore: true,
+            cursor: 'cursor-1',
+            records: [baseRecord({ id: '1' }), baseRecord({ id: '2' })],
+        };
+        const getMySentInboxCredentials = vi.fn().mockResolvedValueOnce(page1);
+
+        const { records, hasMore } = await fetchSentInboxCredentials(
+            { getMySentInboxCredentials },
+            { limit: 1 }
+        );
+
+        expect(records.map(r => r.id)).toEqual(['1']);
+        expect(hasMore).toBe(true);
+    });
+});
+
+describe('toJsonRecord', () => {
+    it('shapes a record for --json output, omitting an absent recipient', () => {
+        const record = baseRecord({ id: 'x' });
+        expect(toJsonRecord(record)).toEqual({
+            id: 'x',
+            status: 'PENDING',
+            recipient: undefined,
+            createdAt: record.createdAt,
+            expiresAt: record.expiresAt,
+            credentialName: undefined,
+            isSigned: true,
+        });
+    });
+
+    it('includes the recipient value only when present', () => {
+        const withValue = baseRecord({ recipient: { type: 'email', value: 'a@example.com' } });
+        expect(toJsonRecord(withValue).recipient).toEqual({
+            type: 'email',
+            value: 'a@example.com',
+        });
+
+        const withoutValue = baseRecord({ recipient: { type: 'phone' } });
+        expect(toJsonRecord(withoutValue).recipient).toEqual({ type: 'phone' });
+    });
+});
+
+describe('inbox list pipeline', () => {
+    it('merges two mocked pages, filters by since, and shapes json records', async () => {
+        const page1 = {
+            hasMore: true,
+            cursor: 'c1',
+            records: [
+                baseRecord({
+                    id: '1',
+                    createdAt: '2026-01-01T00:00:00.000Z',
+                    recipient: { type: 'email', value: 'a@example.com' },
+                }),
+                baseRecord({
+                    id: '2',
+                    createdAt: '2026-01-08T00:00:00.000Z',
+                    recipient: { type: 'phone' },
+                }),
+            ],
+        };
+        const page2 = {
+            hasMore: false,
+            records: [
+                baseRecord({
+                    id: '3',
+                    createdAt: '2026-01-09T00:00:00.000Z',
+                    recipient: { type: 'email' },
+                }),
+            ],
+        };
+        const getMySentInboxCredentials = vi
+            .fn()
+            .mockResolvedValueOnce(page1)
+            .mockResolvedValueOnce(page2);
+
+        const { records, hasMore } = await fetchSentInboxCredentials(
+            { getMySentInboxCredentials },
+            { limit: 10 }
+        );
+        const since = parseSince('7d', new Date('2026-01-10T00:00:00.000Z'));
+        const filtered = filterSince(records, since);
+
+        expect(filtered.map(r => r.id)).toEqual(['2', '3']);
+        expect(hasMore).toBe(false);
+        expect(filtered.map(toJsonRecord)).toEqual([
+            {
+                id: '2',
+                status: 'PENDING',
+                recipient: { type: 'phone' },
+                createdAt: '2026-01-08T00:00:00.000Z',
+                expiresAt: page1.records[1]!.expiresAt,
+                credentialName: undefined,
+                isSigned: true,
+            },
+            {
+                id: '3',
+                status: 'PENDING',
+                recipient: { type: 'email' },
+                createdAt: '2026-01-09T00:00:00.000Z',
+                expiresAt: page2.records[0]!.expiresAt,
+                credentialName: undefined,
+                isSigned: true,
+            },
+        ]);
+    });
+});

package/src/inbox.ts

@@ -0,0 +1,221 @@
+import { Option, type Command } from 'commander';
+import type {
+    InboxCredentialQuery,
+    InboxCredentialType,
+    PaginationOptionsType,
+} from '@learncard/types';
+
+import {
+    connect,
+    connectAsManaged,
+    loadProject,
+    type NetworkCard,
+    type ProjectOptions,
+} from './project';
+import { out } from './out';
+
+export interface InboxRecipient {
+    type?: string;
+    value?: string;
+}
+
+/**
+ * The network's current inbox listing carries no recipient contact info per record
+ * (only the send-time response does). `recipient` is modeled as optional so this type
+ * stays compatible with today's API.
+ */
+export type SentInboxRecord = InboxCredentialType & { recipient?: InboxRecipient };
+
+export interface InboxJsonRecord {
+    id: string;
+    status: string;
+    recipient?: { type?: string; value?: string };
+    createdAt: string;
+    expiresAt: string;
+    credentialName?: string;
+    isSigned: boolean;
+}
+
+const STATUS_VALUES = ['PENDING', 'ISSUED', 'EXPIRED', 'DELIVERED', 'CLAIMED'] as const;
+type InboxStatus = (typeof STATUS_VALUES)[number];
+
+export const isInboxStatus = (value: string): value is InboxStatus =>
+    (STATUS_VALUES as readonly string[]).includes(value);
+
+export const parseStatus = (value: string | undefined): InboxStatus | undefined => {
+    if (value === undefined) return undefined;
+    const upper = value.toUpperCase();
+    if (!isInboxStatus(upper))
+        throw new Error(
+            `Unknown --status "${value}". Use PENDING, ISSUED, or EXPIRED (DELIVERED and CLAIMED are deprecated aliases).`
+        );
+    return upper;
+};
+
+export const parseLimit = (value: string | undefined): number => {
+    if (value === undefined) return 50;
+    const limit = Number(value);
+    if (!Number.isInteger(limit) || limit < 1)
+        throw new Error(`Invalid --limit "${value}". Use a positive whole number.`);
+    return limit;
+};
+
+const DURATION_PATTERN = /^(\d+)\s*(d|h|m)$/i;
+const MS_PER_UNIT = { d: 86_400_000, h: 3_600_000, m: 60_000 } as const;
+
+/** Parses `7d` / `24h` / `30m` (relative to `now`) or an ISO timestamp into a cutoff Date. */
+export const parseSince = (value: string, now: Date = new Date()): Date => {
+    const match = value.match(DURATION_PATTERN);
+    if (match) {
+        const amount = Number(match[1]);
+        const unit = match[2]!.toLowerCase() as keyof typeof MS_PER_UNIT;
+        return new Date(now.getTime() - amount * MS_PER_UNIT[unit]);
+    }
+    const parsed = new Date(value);
+    if (Number.isNaN(parsed.getTime()))
+        throw new Error(`Invalid --since value "${value}". Use 7d, 24h, 30m, or an ISO timestamp.`);
+    return parsed;
+};
+
+/** Keeps only records created at or after `since`; a no-op when `since` is undefined. */
+export const filterSince = <T extends { createdAt: string }>(records: T[], since?: Date): T[] => {
+    if (!since) return records;
+    const cutoff = since.getTime();
+    return records.filter(record => new Date(record.createdAt).getTime() >= cutoff);
+};
+
+export interface FetchSentInboxOptions {
+    limit: number;
+    currentStatus?: InboxStatus;
+}
+
+export interface FetchSentInboxResult {
+    records: SentInboxRecord[];
+    hasMore: boolean;
+}
+
+/** Cursor-paginates the network's sent-inbox listing until `hasMore` is false or `limit` is reached. */
+export const fetchSentInboxCredentials = async (
+    card: Pick<NetworkCard['invoke'], 'getMySentInboxCredentials'>,
+    options: FetchSentInboxOptions
+): Promise<FetchSentInboxResult> => {
+    const records: SentInboxRecord[] = [];
+    let cursor: string | undefined;
+    let serverHasMore = true;
+
+    while (serverHasMore && records.length < options.limit) {
+        const query: Partial<PaginationOptionsType> & { query?: InboxCredentialQuery } = {
+            limit: Math.max(1, options.limit - records.length),
+            ...(cursor ? { cursor } : {}),
+            ...(options.currentStatus ? { query: { currentStatus: options.currentStatus } } : {}),
+        };
+        const page = await card.getMySentInboxCredentials(query);
+        records.push(...page.records);
+        serverHasMore = page.hasMore;
+        cursor = page.cursor;
+    }
+
+    const total = records.length;
+    return {
+        records: records.slice(0, options.limit),
+        hasMore: serverHasMore || total > options.limit,
+    };
+};
+
+/** Shapes a record for `--json` output; `recipient` is omitted when the metadata lacks it. */
+export const toJsonRecord = (record: SentInboxRecord): InboxJsonRecord => ({
+    id: record.id,
+    status: record.currentStatus,
+    recipient: record.recipient
+        ? {
+              type: record.recipient.type,
+              ...(record.recipient.value ? { value: record.recipient.value } : {}),
+          }
+        : undefined,
+    createdAt: record.createdAt,
+    expiresAt: record.expiresAt,
+    credentialName: record.credentialName,
+    isSigned: record.isSigned,
+});
+
+const formatRow = (record: SentInboxRecord): string => {
+    const created = record.createdAt.replace('T', ' ').slice(0, 19);
+    const recipient = record.recipient
+        ? `${record.recipient.type ?? '?'}${record.recipient.value ? `:${record.recipient.value}` : ''}`
+        : '—';
+    return `${record.id}  ${record.currentStatus.padEnd(8)}  ${recipient}  ${created}  ${record.credentialName ?? ''}`;
+};
+
+export type InboxListOptions = ProjectOptions & {
+    as?: string;
+    status?: string;
+    since?: string;
+
+    limit?: string;
+};
+
+export const runInboxList = async (options: InboxListOptions): Promise<void> => {
+    const project = await loadProject(process.cwd());
+    const learnCard = options.as
+        ? await connectAsManaged(project, options, options.as)
+        : await connect(project, options);
+
+    const currentStatus = parseStatus(options.status);
+    const limit = parseLimit(options.limit);
+    const since = options.since ? parseSince(options.since) : undefined;
+
+    const { records: fetched, hasMore } = await fetchSentInboxCredentials(learnCard.invoke, {
+        limit,
+        currentStatus,
+    });
+
+    const filtered = filterSince(fetched, since);
+
+    if (!filtered.length) {
+        out.log('No sent inbox credentials match. Try widening --since or dropping --status.');
+        out.set({ records: [], hasMore });
+        return;
+    }
+
+    out.log('issuanceId  status  recipient  created  name');
+    for (const record of filtered) out.log(formatRow(record));
+    if (hasMore) out.log('…more. Raise --limit to see additional sends.');
+
+    out.set({ records: filtered.map(toJsonRecord), hasMore });
+};
+
+export const registerInboxCommand = (
+    program: Command,
+    run: (
+        command: string,
+        options: { json?: boolean },
+        action: (didkit: Promise<Buffer>) => Promise<void>,
+        wrap?: boolean
+    ) => Promise<void>
+): void => {
+    const inbox = program
+        .command('inbox')
+        .description('Credentials sent through the inbox (email/phone claim flow).');
+    inbox
+        .command('list')
+        .description('List credentials you sent through the inbox.')
+        .addOption(
+            new Option('--as <profileId>', 'list credentials sent by a profile you manage').env(
+                'LEARNCARD_AS'
+            )
+        )
+        .option('--status <status>', 'PENDING, ISSUED, or EXPIRED')
+        .option(
+            '--since <duration|iso>',
+            'only sends at/after this: 7d, 24h, 30m, or an ISO timestamp'
+        )
+
+        .option('--limit <n>', 'how many to list (default: 50)')
+        .option('--network <url>', 'network tRPC URL or staging (default: production)')
+        .option('--json', 'print a single JSON result on stdout')
+        .action(options =>
+            run('inbox list', options, async didkit => {
+                await runInboxList({ ...options, didkit });
+            })
+        );
+};

package/src/index.tsx

@@ -12,7 +12,7 @@ import * as types from '@learncard/types';
 import { getLinkedClaimsPlugin } from '@learncard/linked-claims-plugin';
 import gradient from 'gradient-string';
 import figlet from 'figlet';
-import { program } from 'commander';
+import { Option, program } from 'commander';
 import clipboard from 'clipboardy';
 
 import { getLerRsPlugin } from '@learncard/ler-rs-plugin';
@@ -32,6 +32,13 @@ import {
     createExportLearnCardBundleHelper,
     createRestoreLearnCardFromBundleHelper,
 } from './replHelpers';
+import { registerOrgCommand } from './org';
+import { registerDoctorCommand } from './doctor';
+import { registerClrCommand } from './clr';
+import { registerInboxCommand } from './inbox';
+import { registerRefreshCommand } from './refresh';
+import { registerWhoamiCommand } from './whoami';
+import { registerPromoteCommand } from './promote';
 
 import packageJson from '../package.json';
 
@@ -329,9 +336,9 @@ const startCliRepl = async (colorize: (input: string) => string): Promise<void>
 };
 
 program
-    .command('send <email>')
+    .command('send [recipient]')
     .description(
-        'Send a "Quickstart Complete" badge to an email address. Creates .env and send.mjs in the current folder.'
+        'Send a "Quickstart Complete" badge to an email, phone number, profile ID, or DID (prompts if omitted). Creates .env and send.mjs in the current folder.'
     )
     .option('-y, --yes', 'accept defaults without prompting')
     .option('--name <displayName>', 'display name for your issuer profile')
@@ -342,7 +349,17 @@ program
         'public handle for your profile (default: derived from the display name)'
     )
     .option('--network <url>', 'network tRPC URL (default: production)')
-    .option('--template', 'send using a reusable template and hosted signing authority')
+    .addOption(
+        new Option(
+            '--as <profileId>',
+            'send as a profile you manage (from `org apply`), signed with its did:web'
+        ).env('LEARNCARD_AS')
+    )
+    .option(
+        '--template',
+        'send using a reusable template and hosted signing authority (default once setup-signing or org apply has run)'
+    )
+    .option('--no-template', 'sign with the local key even if a signing authority is registered')
     .option('--template-uri <uri>', 'send from a specific template (implies --template)')
     .option('--webhook-url <url>', 'receive ISSUANCE_DELIVERED / ISSUANCE_CLAIMED at this URL')
     .option('--suppress-delivery', 'skip the claim email; you deliver inbox.claimUrl yourself')
@@ -353,7 +370,7 @@ program
     .option('--json', 'print a single JSON result on stdout')
     .action(
         async (
-            email: string,
+            recipient: string | undefined,
             opts: {
                 yes?: boolean;
                 name?: string;
@@ -371,7 +388,7 @@ program
                 require.resolve('@learncard/didkit-plugin/dist/didkit/didkit_wasm_bg.wasm')
             );
             try {
-                await runSend(email, { ...opts, didkit });
+                await runSend(recipient, { ...opts, didkit });
                 if (out.json) {
                     process.stdout.write(
                         JSON.stringify({ ok: true, command: 'send', ...out.result }) + '\n'
@@ -389,7 +406,11 @@ program
                 }
                 console.error(`\n${firstLine}`);
                 // Input mistakes explain themselves; keep the docs link for network/auth failures.
-                if (!/is not an email address/.test(firstLine))
+                if (
+                    !/is not an email address|is a placeholder address|A recipient is required/.test(
+                        firstLine
+                    )
+                )
                     console.error(
                         'Troubleshooting: https://docs.learncard.com/start-here/your-first-integration#if-something-goes-wrong'
                     );
@@ -441,6 +462,32 @@ const runCommand = async (
     }
 };
 
+program
+    .command('demo')
+    .description('Guided demonstrations using real LearnCard credentials.')
+    .command('refresh')
+    .description('Send a demo badge, publish an update, and refresh the recipient’s copy.')
+    .option('--inbox', 'use Universal Inbox deferred issuance for an address with no account')
+    .option('--ui', 'claim and refresh in the local LearnCard app (interactive only)')
+    .option('--app-url <url>', 'local LearnCard app URL for --ui (default: http://localhost:3000)')
+    .option(
+        '--lca-url <url>',
+        'local LCA URL for --inbox terminal mode (default: http://localhost:5100/trpc)'
+    )
+    .option(
+        '--email [address]',
+        'real-email mode: request a provisional claim email to your own address (requires --inbox --ui; prompts when omitted)'
+    )
+    .option('-y, --yes', 'run all steps without pausing')
+    .option('--network <url>', 'network tRPC URL or staging', 'http://localhost:4000/trpc')
+    .option('--json', 'print a single JSON result on stdout (no pauses)')
+    .action(options =>
+        runCommand('demo refresh', options, async didkit => {
+            const { runDemoRefreshCommand } = await import('./demo-refresh-command');
+            await runDemoRefreshCommand({ ...options, didkit });
+        })
+    );
+
 commandOptions(
     program.command('consent-contract').description("Connect a user's LearnCard to your platform.")
 )
@@ -597,9 +644,18 @@ commandOptions(
         })
     );
 
+registerOrgCommand(program, runCommand);
+registerDoctorCommand(program, runCommand);
+registerClrCommand(program, runCommand);
+registerInboxCommand(program, runCommand);
+registerRefreshCommand(program, runCommand);
+registerWhoamiCommand(program, runCommand);
+registerPromoteCommand(program, runCommand);
+
 const JOURNEY = [
     'send',
     'status',
+    'whoami',
     'setup-signing',
     'token',
     'webhook',
@@ -608,6 +664,12 @@ const JOURNEY = [
     'verify',
     'revoke',
     'open',
+    'org',
+    'doctor',
+    'promote',
+    'clr',
+    'inbox',
+    'refresh',
     'init',
     'repl',
 ];
@@ -625,7 +687,7 @@ program
     })
     .addHelpText(
         'before',
-        '\nStart here:  npx @learncard/cli send you@example.com\nThen:        npx @learncard/cli status\n'
+        '\nStart here:  npx @learncard/cli send\nThen:        npx @learncard/cli status\n'
     )
     .addHelpText(
         'after',

package/src/init.ts

@@ -22,5 +22,5 @@ export const runInit = async (options: ProjectOptions): Promise<void> => {
         envPath: project.envPath,
     });
     out.log(fresh ? 'Ready. Your identity is in .env (keep it out of git).' : 'Already set up.');
-    out.log('Next: npx @learncard/cli send you@example.com');
+    out.log('Next: npx @learncard/cli send');
 };

package/src/open.ts

@@ -120,7 +120,7 @@ export const runOpen = async (
     const seed = project.env.SECURE_SEED;
     if (!seed)
         throw new Error(
-            'No SECURE_SEED in .env. Run a command that creates one first, e.g. npx @learncard/cli send you@example.com'
+            'No SECURE_SEED in .env. Run a command that creates one first, e.g. npx @learncard/cli send'
         );
 
     const path = openPath(target, project.env);