@learncard/cli 3.4.17 → 3.5.1

package/src/send.ts

@@ -0,0 +1,245 @@
+import fs from 'fs/promises';
+import path from 'path';
+import { randomUUID } from 'node:crypto';
+import {
+    connect,
+    createPrompts,
+    ensureIdentity,
+    ensureProfile,
+    loadProject,
+    saveProject,
+    type ProjectOptions,
+    localizeSnippet,
+    resolveServices,
+} from './project';
+import { setupSigning } from './setup-signing';
+import { SEND_MJS, SEND_FROM_TEMPLATE_MJS } from './generated/snippets';
+import { out } from './out';
+
+export { SEND_MJS } from './generated/snippets';
+export { parseEnv, upsertEnv, toProfileId } from './project';
+export type SendEnv = { SECURE_SEED?: string; PROFILE_ID?: string };
+export type Badge = { name: string; description: string };
+export const DEFAULT_BADGE: Badge = {
+    name: 'Quickstart Complete',
+    description: 'Sent a verifiable credential with LearnCard.',
+};
+
+export const quickstartCredential = (issuerDid: string, badge: Badge = DEFAULT_BADGE) => ({
+    '@context': [
+        'https://www.w3.org/ns/credentials/v2',
+        'https://purl.imsglobal.org/spec/ob/v3p0/context-3.0.3.json',
+    ],
+    type: ['VerifiableCredential', 'OpenBadgeCredential'],
+    issuer: issuerDid,
+    validFrom: new Date().toISOString(),
+    name: badge.name,
+    credentialSubject: {
+        type: ['AchievementSubject'],
+        achievement: {
+            id: `urn:uuid:${randomUUID()}`,
+            type: ['Achievement'],
+            name: badge.name,
+            description: badge.description,
+            criteria: { narrative: 'Ran the LearnCard quickstart.' },
+        },
+    },
+});
+
+export const templateCredential = (issuerDid: string, badge: Badge = DEFAULT_BADGE) => {
+    const credential = quickstartCredential(issuerDid, badge);
+    credential['@context'].push('https://ctx.learncard.com/boosts/1.0.1.json');
+    credential.type.push('BoostCredential');
+    return credential;
+};
+
+type SendOptions = ProjectOptions & {
+    badge?: string;
+    description?: string;
+    template?: boolean;
+    templateUri?: string;
+    webhookUrl?: string;
+    suppressDelivery?: boolean;
+    guardianEmail?: string;
+};
+
+type SendDeliveryOptions = {
+    webhookUrl?: string;
+    suppressDelivery?: boolean;
+    guardianEmail?: string;
+};
+
+const sendOptions = (options: SendOptions): { options?: SendDeliveryOptions } => {
+    const picked: SendDeliveryOptions = {
+        webhookUrl: options.webhookUrl,
+        suppressDelivery: options.suppressDelivery,
+        guardianEmail: options.guardianEmail,
+    };
+    return Object.values(picked).some(v => v !== undefined) ? { options: picked } : {};
+};
+
+/** Inserts the effective send() delivery options right after `anchor` so a re-run of the
+ *  generated script reproduces the same call. */
+const withDeliveryOptions = (
+    content: string,
+    anchor: string,
+    deliveryOptions?: SendDeliveryOptions
+): string =>
+    deliveryOptions
+        ? content.replace(
+              anchor,
+              () => `${anchor}\n    options: ${JSON.stringify(deliveryOptions)},`
+          )
+        : content;
+
+/** Substitute the user's choices into the template that the docs snippet uses. */
+export const personalizeSendMjs = (
+    displayName: string,
+    badge: Badge,
+    deliveryOptions?: SendDeliveryOptions
+): string =>
+    withDeliveryOptions(
+        SEND_MJS.replace(
+            "displayName: 'My Organization'",
+            () => `displayName: ${JSON.stringify(displayName)}`
+        )
+            .split("'Quickstart Complete'")
+            .join(JSON.stringify(badge.name))
+            .replace("'Sent a verifiable credential with LearnCard.'", () =>
+                JSON.stringify(badge.description)
+            ),
+        '    signedCredential: credential,',
+        deliveryOptions
+    );
+
+/** Substitute the effective send() delivery options into the from-template script. */
+export const personalizeSendFromTemplateMjs = (deliveryOptions?: SendDeliveryOptions): string =>
+    withDeliveryOptions(
+        SEND_FROM_TEMPLATE_MJS,
+        '    templateUri: process.env.TEMPLATE_URI,',
+        deliveryOptions
+    );
+
+const EMAIL = /^[^\s@]+@[^\s@]+\.[^\s@]+$/;
+const PHONE = /^\+?\d{10,15}$/;
+
+export const runSend = async (recipientEmail: string, options: SendOptions): Promise<void> => {
+    if (!EMAIL.test(recipientEmail) && !PHONE.test(recipientEmail))
+        throw new Error(
+            `"${recipientEmail}" is not an email address or phone number. Example: npx @learncard/cli send you@example.com`
+        );
+    const cwd = process.cwd();
+    const project = await loadProject(cwd);
+    const prompts = createPrompts(options.yes);
+    let displayName: string | undefined;
+    let badge: Badge;
+    try {
+        const needsName = !project.env.PROFILE_ID && !options.profileId && !options.name;
+        displayName = needsName
+            ? await prompts.ask('Display name for your issuer profile', 'My Organization')
+            : options.name;
+        badge = {
+            name: options.badge ?? (await prompts.ask('Badge name', DEFAULT_BADGE.name)),
+            description: options.description ?? DEFAULT_BADGE.description,
+        };
+    } finally {
+        prompts.close();
+    }
+    const identity = await ensureIdentity(project, { ...options, name: displayName, yes: true });
+    const useTemplate = options.template || !!options.templateUri;
+    const learnCard = useTemplate
+        ? await connect(project, { ...options, lca: true })
+        : await connect(project, options);
+    await ensureProfile(learnCard, identity, project);
+
+    const effectiveSendOptions = sendOptions(options);
+    let result;
+    if (useTemplate) {
+        // This branch connected with the LCA plugin; setupSigning accepts its required methods.
+        await setupSigning(
+            project,
+            learnCard as Awaited<
+                ReturnType<typeof import('@learncard/lca-api-plugin').initLCALearnCard>
+            >
+        );
+        if (options.templateUri) {
+            out.log(`Sending from template ${options.templateUri}.`);
+            if (!project.env.TEMPLATE_URI) {
+                await saveProject(project, { TEMPLATE_URI: options.templateUri });
+            }
+        } else if (!project.env.TEMPLATE_URI) {
+            const uri = await learnCard.invoke.createBoost(
+                templateCredential(learnCard.id.did(), badge),
+                {
+                    name: badge.name,
+                    category: 'Achievement',
+                    status: 'LIVE',
+                }
+            );
+            await saveProject(project, { TEMPLATE_URI: uri });
+        } else {
+            out.log(
+                `Reusing template ${project.env.TEMPLATE_URI}; its saved badge name and description are unchanged.`
+            );
+        }
+        result = await learnCard.invoke.send({
+            type: 'boost',
+            recipient: recipientEmail,
+            templateUri: options.templateUri ?? project.env.TEMPLATE_URI!,
+            ...effectiveSendOptions,
+        });
+    } else {
+        const credential = await learnCard.invoke.issueCredential(
+            quickstartCredential(learnCard.id.did(), badge)
+        );
+        result = await learnCard.invoke.send({
+            type: 'boost',
+            recipient: recipientEmail,
+            signedCredential: credential,
+            ...effectiveSendOptions,
+        });
+    }
+    out.log('');
+    if (result.inbox?.status === 'PENDING') {
+        out.log(
+            `Sent. ${recipientEmail} will get a claim email. You can also share this link directly:\n${result.inbox.claimUrl}`
+        );
+    } else {
+        out.log(
+            `Delivered. ${recipientEmail} already uses LearnCard — the credential is in their wallet.`
+        );
+    }
+    out.log(`Reusable template for this badge: ${result.uri}`);
+    const filename = useTemplate ? 'send-from-template.mjs' : 'send.mjs';
+    const sendPath = path.join(cwd, filename);
+    let wroteSendFile = false;
+    if (!(await fs.stat(sendPath).catch(() => null))) {
+        await fs.writeFile(
+            sendPath,
+            localizeSnippet(
+                useTemplate
+                    ? personalizeSendFromTemplateMjs(effectiveSendOptions.options)
+                    : personalizeSendMjs(identity.displayName, badge, effectiveSendOptions.options),
+                resolveServices(project.env, options.network)
+            )
+        );
+        wroteSendFile = true;
+        out.log(
+            `\nThe code that just ran is in ./${filename} — run it yourself:\n  npm install @learncard/init\n  node --env-file=.env ${filename} ${recipientEmail}`
+        );
+    }
+    out.log(`Check whether it was claimed: npx @learncard/cli status ${result.activityId}`);
+    out.log(`See it in the app: npx @learncard/cli open${options.template ? ' template' : ''}`);
+    out.set({
+        profileId: identity.profileId,
+        did: learnCard.id.did(),
+        recipient: recipientEmail,
+        status: result.inbox?.status === 'PENDING' ? 'PENDING' : 'ISSUED',
+        ...(result.inbox?.claimUrl && { claimUrl: result.inbox.claimUrl }),
+        templateUri: result.uri,
+        activityId: result.activityId,
+        ...(result.credentialUri && { credentialUri: result.credentialUri }),
+        ...(result.inbox?.issuanceId && { issuanceId: result.inbox.issuanceId }),
+        files: wroteSendFile ? [`./${filename}`] : [],
+    });
+};

package/src/setup-signing.test.ts

@@ -0,0 +1,62 @@
+import { describe, expect, it, vi } from 'vitest';
+import fs from 'node:fs/promises';
+import os from 'node:os';
+import path from 'node:path';
+import { authorityName, setupSigning } from './setup-signing';
+import { loadProject } from './project';
+
+describe('signing authority setup', () => {
+    it('defaults to default-issuer and reuses the project selection', () => {
+        const project = { env: {}, existing: '', envPath: '/unused/.env' };
+        expect(authorityName(project)).toBe('default-issuer');
+        expect(authorityName({ ...project, env: { SIGNING_AUTHORITY_NAME: 'existing' } })).toBe(
+            'existing'
+        );
+        expect(authorityName(project, 'custom')).toBe('custom');
+    });
+    it('resumes after failed registration and leaves an existing primary untouched', async () => {
+        const cwd = await fs.mkdtemp(path.join(os.tmpdir(), 'lc-signing-'));
+        const log = vi.spyOn(console, 'log').mockImplementation(() => {});
+        const authority = {
+            name: 'default-issuer',
+            endpoint: 'https://issuer.example/api',
+            did: 'did:key:issuer',
+            ownerDid: 'did:key:owner',
+        };
+        const invoke = {
+            getRegisteredSigningAuthorities: vi.fn().mockResolvedValue([]),
+            getSigningAuthorities: vi.fn().mockResolvedValueOnce([]).mockResolvedValue([authority]),
+            createSigningAuthority: vi.fn().mockResolvedValue(authority),
+            registerSigningAuthority: vi
+                .fn()
+                .mockRejectedValueOnce(new Error('Connection lost'))
+                .mockResolvedValue(true),
+            setPrimaryRegisteredSigningAuthority: vi.fn().mockResolvedValue(true),
+        };
+        try {
+            const project = await loadProject(cwd);
+            await expect(setupSigning(project, { invoke })).rejects.toThrow('Connection lost');
+            await setupSigning(project, { invoke });
+            expect(invoke.createSigningAuthority).toHaveBeenCalledTimes(1);
+            expect(project.env.SIGNING_AUTHORITY_ENDPOINT).toBe(authority.endpoint);
+            invoke.getRegisteredSigningAuthorities.mockResolvedValue([
+                {
+                    signingAuthority: { endpoint: authority.endpoint },
+                    relationship: { name: authority.name, did: authority.did, isPrimary: true },
+                },
+            ]);
+            await setupSigning(project, { invoke });
+            expect(invoke.createSigningAuthority).toHaveBeenCalledTimes(1);
+            expect(invoke.setPrimaryRegisteredSigningAuthority).toHaveBeenCalledTimes(1);
+            expect(log).toHaveBeenCalledWith(
+                'Signing authority "default-issuer" is already your primary.'
+            );
+            const demoProject = { env: {}, existing: '', envPath: '/unused/.env' };
+            await setupSigning(demoProject, { invoke }, undefined, { persist: false });
+            expect(demoProject.env).toEqual({});
+        } finally {
+            log.mockRestore();
+            await fs.rm(cwd, { recursive: true, force: true });
+        }
+    });
+});

package/src/setup-signing.ts

@@ -0,0 +1,185 @@
+import type { LCALearnCard } from '@learncard/lca-api-plugin';
+import {
+    connect,
+    ensureIdentity,
+    ensureProfile,
+    loadProject,
+    saveProject,
+    type Project,
+    type ProjectOptions,
+    type NetworkCard,
+} from './project';
+import { out } from './out';
+
+export const authorityName = (project: Project, name?: string): string =>
+    name ?? project.env.SIGNING_AUTHORITY_NAME ?? 'default-issuer';
+
+export interface SigningAuthorityResult {
+    name: string;
+    endpoint: string;
+    did: string;
+    alreadyConfigured: boolean;
+}
+
+type SigningCard = {
+    invoke: Pick<
+        LCALearnCard['invoke'],
+        | 'getRegisteredSigningAuthorities'
+        | 'getSigningAuthorities'
+        | 'setPrimaryRegisteredSigningAuthority'
+        | 'createSigningAuthority'
+        | 'registerSigningAuthority'
+    >;
+};
+
+/** Create and register a hosted signer once; also repair a changed primary selection. */
+export const setupSigning = async (
+    project: Project,
+    learnCard: SigningCard,
+    requestedName?: string,
+    options: { persist?: boolean } = {}
+): Promise<SigningAuthorityResult> => {
+    const name = authorityName(project, requestedName);
+    const registered = (await learnCard.invoke.getRegisteredSigningAuthorities()).find(
+        authority =>
+            authority.relationship.name === name &&
+            (requestedName ||
+                !project.env.SIGNING_AUTHORITY_ENDPOINT ||
+                authority.signingAuthority.endpoint === project.env.SIGNING_AUTHORITY_ENDPOINT)
+    );
+    if (registered) {
+        const endpoint = registered.signingAuthority.endpoint;
+        if (!registered.relationship.isPrimary) {
+            if (!(await learnCard.invoke.setPrimaryRegisteredSigningAuthority(endpoint, name))) {
+                throw new Error(
+                    'Could not select the primary signing authority. Please try again.'
+                );
+            }
+        }
+        if (options.persist !== false) {
+            await saveProject(project, {
+                SIGNING_AUTHORITY_NAME: name,
+                SIGNING_AUTHORITY_ENDPOINT: endpoint,
+            });
+        }
+        out.log(`Signing authority "${name}" is already your primary.`);
+        return { name, endpoint, did: registered.relationship.did, alreadyConfigured: true };
+    }
+    const hosted = await learnCard.invoke.getSigningAuthorities();
+    if (!hosted) throw new Error('Could not look up hosted signing authorities. Please try again.');
+    const existing = hosted.find(authority => authority.name === name);
+    const authority = existing || (await learnCard.invoke.createSigningAuthority(name));
+    if (!authority || !authority.endpoint || !authority.did)
+        throw new Error('Could not create signing authority. Please try again.');
+    const registeredSuccessfully = await learnCard.invoke.registerSigningAuthority(
+        authority.endpoint,
+        authority.name,
+        authority.did
+    );
+    if (!registeredSuccessfully)
+        throw new Error('Could not register signing authority. Please try again.');
+    if (
+        !(await learnCard.invoke.setPrimaryRegisteredSigningAuthority(
+            authority.endpoint,
+            authority.name
+        ))
+    ) {
+        throw new Error('Could not select the primary signing authority. Please try again.');
+    }
+    if (options.persist !== false) {
+        await saveProject(project, {
+            SIGNING_AUTHORITY_NAME: authority.name,
+            SIGNING_AUTHORITY_ENDPOINT: authority.endpoint,
+        });
+    }
+    out.log(`LearnCard will now sign credentials for ${project.env.PROFILE_ID}.`);
+    out.log('What this did:');
+    out.log(
+        existing
+            ? `  const authority = (await learnCard.invoke.getSigningAuthorities()).find(authority => authority.name === ${JSON.stringify(name)});`
+            : `  const authority = await learnCard.invoke.createSigningAuthority(${JSON.stringify(name)});`
+    );
+    out.log(
+        '  await learnCard.invoke.registerSigningAuthority(authority.endpoint, authority.name, authority.did);'
+    );
+    out.log(
+        '  await learnCard.invoke.setPrimaryRegisteredSigningAuthority(authority.endpoint, authority.name);'
+    );
+    return {
+        name: authority.name,
+        endpoint: authority.endpoint,
+        did: authority.did,
+        alreadyConfigured: false,
+    };
+};
+
+type SetupSigningOptions = ProjectOptions & { endpoint?: string; did?: string };
+
+/** Register a signing service you run yourself instead of a LearnCard-hosted one. */
+const registerOwnAuthority = async (
+    project: Project,
+    learnCard: {
+        invoke: Pick<
+            NetworkCard['invoke'],
+            'registerSigningAuthority' | 'setPrimaryRegisteredSigningAuthority'
+        >;
+    },
+    name: string,
+    endpoint: string,
+    did: string
+) => {
+    if (!/^https:\/\//.test(endpoint)) throw new Error('--endpoint must be an https:// URL.');
+    if (!/^did:/.test(did)) throw new Error('--did must be a DID (did:web:..., did:key:...).');
+    if (!(await learnCard.invoke.registerSigningAuthority(endpoint, name, did)))
+        throw new Error('Could not register the signing authority.');
+    if (!(await learnCard.invoke.setPrimaryRegisteredSigningAuthority(endpoint, name)))
+        throw new Error('Could not set the signing authority as primary.');
+    await saveProject(project, {
+        SIGNING_AUTHORITY_NAME: name,
+        SIGNING_AUTHORITY_ENDPOINT: endpoint,
+    });
+    out.log(`Your service at ${endpoint} will now sign credentials for this profile.`);
+    out.log('What this did:');
+    out.log(
+        `  await learnCard.invoke.registerSigningAuthority(${JSON.stringify(endpoint)}, ${JSON.stringify(name)}, ${JSON.stringify(did)});`
+    );
+    out.log(
+        `  await learnCard.invoke.setPrimaryRegisteredSigningAuthority(${JSON.stringify(endpoint)}, ${JSON.stringify(name)});`
+    );
+    return { name, endpoint, did, alreadyConfigured: false };
+};
+
+export const runSetupSigning = async (options: SetupSigningOptions): Promise<void> => {
+    const project = await loadProject(process.cwd());
+    const identity = await ensureIdentity(project, { ...options, name: undefined });
+    if ((options.endpoint && !options.did) || (!options.endpoint && options.did))
+        throw new Error('Pass both --endpoint and --did to register your own signing service.');
+    let authority;
+    if (options.endpoint) {
+        const learnCard = await connect(project, options);
+        await ensureProfile(learnCard, identity, project);
+        authority = await registerOwnAuthority(
+            project,
+            learnCard,
+            options.name ?? 'my-issuer',
+            options.endpoint,
+            options.did!
+        );
+    } else {
+        const learnCard = await connect(project, { ...options, lca: true });
+        await ensureProfile(learnCard, identity, project);
+        authority = await setupSigning(project, learnCard, options.name);
+    }
+    out.set({
+        profileId: identity.profileId,
+        signingAuthority: {
+            name: authority.name,
+            endpoint: authority.endpoint,
+            did: authority.did,
+        },
+        alreadyConfigured: authority.alreadyConfigured,
+    });
+    out.log(
+        'Send from a template: npx @learncard/cli send you@example.com --template\nSee it in the app: npx @learncard/cli open'
+    );
+};

package/src/snippet-files.ts

@@ -0,0 +1,16 @@
+import fs from 'node:fs/promises';
+import path from 'node:path';
+import { out } from './out';
+
+/** Preserve files a developer may already have customized. Returns whether this run wrote it. */
+export const writeSnippet = async (filename: string, source: string): Promise<boolean> => {
+    try {
+        await fs.writeFile(path.join(process.cwd(), filename), source, { flag: 'wx' });
+        out.log(`Wrote ./${filename}`);
+        return true;
+    } catch (error) {
+        if ((error as NodeJS.ErrnoException).code !== 'EEXIST') throw error;
+        out.log(`Kept existing ./${filename}`);
+        return false;
+    }
+};

package/src/status.test.ts

@@ -0,0 +1,33 @@
+import { describe, expect, it } from 'vitest';
+import { formatEvent, summarize } from './status';
+
+const created = {
+    activityId: 'a1',
+    eventType: 'CREATED',
+    timestamp: '2026-09-11T18:12:27.116Z',
+    recipientType: 'email',
+    recipientIdentifier: 'jane@example.com',
+    boost: { name: 'Quickstart Complete' },
+};
+
+describe('status', () => {
+    it('reports the latest event as the state and keeps the chain newest-first', () => {
+        const claimed = {
+            ...created,
+            eventType: 'CLAIMED',
+            timestamp: '2026-09-11T18:20:00.000Z',
+            credentialUri: 'lc:network:x/trpc:credential:1',
+        };
+        const s = summarize([created, claimed]);
+        expect(s.state).toBe('CLAIMED');
+        expect(s.credentialUri).toBe('lc:network:x/trpc:credential:1');
+        expect(s.events.map(e => e.type)).toEqual(['CLAIMED', 'CREATED']);
+    });
+
+    it('surfaces the failure reason on FAILED events', () => {
+        const failed = { ...created, eventType: 'FAILED', metadata: { error: 'bad email' } };
+        expect(formatEvent(failed)).toContain('FAILED');
+        expect(formatEvent(failed)).toContain('bad email');
+        expect(summarize([failed]).events[0]).toMatchObject({ type: 'FAILED', error: 'bad email' });
+    });
+});

package/src/status.ts

@@ -0,0 +1,96 @@
+import { connect, ensureIdentity, loadProject, type ProjectOptions } from './project';
+import { out } from './out';
+
+type ActivityEvent = {
+    activityId: string;
+    eventType: string;
+    timestamp: string;
+    recipientType: string;
+    recipientIdentifier: string;
+    credentialUri?: string;
+    status?: string;
+    boost?: { name?: string } | null;
+    metadata?: Record<string, unknown>;
+};
+
+const LATEST_FIRST = (a: ActivityEvent, b: ActivityEvent) => b.timestamp.localeCompare(a.timestamp);
+
+/** One human line per event: time, what happened, to whom. */
+export const formatEvent = (event: ActivityEvent): string => {
+    const when = event.timestamp.replace('T', ' ').slice(0, 19);
+    const failure = event.eventType === 'FAILED' ? `  ${String(event.metadata?.error ?? '')}` : '';
+    return `${when}  ${event.eventType.padEnd(9)} ${event.recipientIdentifier}${failure}`;
+};
+
+/** Collapse a chain into what a developer wants to know: the current state. */
+export const summarize = (chain: ActivityEvent[]) => {
+    const ordered = [...chain].sort(LATEST_FIRST);
+    const latest = ordered[0];
+    const claimed = chain.find(e => e.eventType === 'CLAIMED');
+    return {
+        state: latest?.eventType ?? 'UNKNOWN',
+        recipient: latest?.recipientIdentifier,
+        template: latest?.boost?.name,
+        credentialUri: claimed?.credentialUri ?? latest?.credentialUri,
+        credentialStatus: latest?.status,
+        events: ordered.map(e => ({
+            type: e.eventType,
+            at: e.timestamp,
+            ...(e.eventType === 'FAILED' && e.metadata?.error ? { error: e.metadata.error } : {}),
+        })),
+    };
+};
+
+type StatusOptions = ProjectOptions & { limit?: string; event?: string };
+
+export const runStatus = async (activityId: string | undefined, options: StatusOptions) => {
+    const project = await loadProject(process.cwd());
+    if (!project.env.SECURE_SEED)
+        throw new Error(
+            'No SECURE_SEED in .env. Send something first: npx @learncard/cli send you@example.com'
+        );
+    await ensureIdentity(project, options);
+    const learnCard = await connect(project, options);
+
+    if (activityId) {
+        const chain = (await learnCard.invoke.getActivityChain({ activityId })) as ActivityEvent[];
+        if (!chain.length) throw new Error(`No activity found for ${activityId}.`);
+        const summary = summarize(chain);
+        out.log(`${summary.state}  ${summary.template ?? ''} → ${summary.recipient}`);
+        for (const e of [...chain].sort(LATEST_FIRST)) out.log(`  ${formatEvent(e)}`);
+        if (summary.credentialUri) out.log(`Credential: ${summary.credentialUri}`);
+        if (summary.state !== 'CLAIMED')
+            out.log('Not claimed yet. Re-run to check again, or use `webhook` to be told.');
+        out.set({ activityId, ...summary });
+        return;
+    }
+
+    const limit = Number(options.limit ?? 20);
+    const eventType = options.event?.toUpperCase();
+    const page = await learnCard.invoke.getMyActivities({
+        limit,
+        ...(eventType ? { eventType: eventType as never } : {}),
+    });
+    const records = page.records as ActivityEvent[];
+    if (!records.length) {
+        out.log('No sends yet. Try: npx @learncard/cli send you@example.com');
+        out.set({ activities: [] });
+        return;
+    }
+    out.log('activityId                            state      recipient');
+    for (const r of records)
+        out.log(`${r.activityId}  ${r.eventType.padEnd(9)}  ${r.recipientIdentifier}`);
+    if (page.hasMore)
+        out.log(`…more. Raise --limit or filter with --event claimed|delivered|created.`);
+    out.log('Details for one: npx @learncard/cli status <activityId>');
+    out.set({
+        activities: records.map(r => ({
+            activityId: r.activityId,
+            state: r.eventType,
+            recipient: r.recipientIdentifier,
+            template: r.boost?.name,
+            at: r.timestamp,
+        })),
+        hasMore: page.hasMore,
+    });
+};

package/src/token.test.ts

@@ -0,0 +1,28 @@
+import { describe, expect, it } from 'vitest';
+import { validateScope, SCOPE_RESOURCES } from './token';
+import { SEND_SH } from './generated/snippets';
+import { withEnvTokenLoader } from './project';
+
+describe('token scopes', () => {
+    it('accepts real resource names and wildcards', () => {
+        for (const resource of SCOPE_RESOURCES)
+            expect(validateScope(`${resource}:write`)).toBe(`${resource}:write`);
+        expect(validateScope('  boosts:write   inbox:read ')).toBe('boosts:write inbox:read');
+        expect(validateScope('*:*')).toBe('*:*');
+        expect(validateScope('')).toBe('');
+    });
+    it('rejects unknown resources, stale aliases, and malformed actions', () => {
+        expect(() => validateScope('unicorns:write')).toThrow('Unknown scope resource');
+        expect(() => validateScope('profile:write')).toThrow('profiles');
+        expect(() => validateScope('boosts:admin')).toThrow('read, write, delete');
+        expect(() => validateScope('boosts:write:extra')).toThrow();
+    });
+    it('writes send.sh that reads API_TOKEN from .env without executing it', () => {
+        const written = withEnvTokenLoader(SEND_SH);
+        expect(written).toContain("sed -n 's/^API_TOKEN=//p' .env");
+        expect(written).not.toMatch(/tr -d/);
+        expect(written).toContain('Bearer $TOKEN');
+        expect(written).not.toContain('. .env');
+        expect(written).not.toContain('source .env');
+    });
+});