@learncard/cli 3.4.17 → 3.5.1

package/package.json

@@ -1,40 +1,37 @@
 {
     "name": "@learncard/cli",
-    "version": "3.4.17",
+    "version": "3.5.1",
     "description": "Command Line Interface for LearnCard",
     "main": "dist/index.js",
     "bin": "dist/index.js",
     "scripts": {
-        "start": "bun --conditions=development src/index.tsx",
-        "start:built": "rollup -c && node --enable-source-maps dist/index.js",
-        "dev": "bun --conditions=development src/index.tsx",
-        "build": "rollup -c",
-        "test": "vitest run",
-        "test:watch": "vitest",
-        "test:coverage": "vitest run --coverage"
+        "start": "bun scripts/embed-snippets.ts && bun --conditions=development src/index.tsx",
+        "start:built": "bun run build && node --enable-source-maps dist/index.js",
+        "dev": "bun run start",
+        "build": "bun scripts/embed-snippets.ts && rollup -c",
+        "test": "bun scripts/embed-snippets.ts && vitest run",
+        "test:watch": "bun scripts/embed-snippets.ts && vitest",
+        "test:coverage": "bun scripts/embed-snippets.ts && vitest run --coverage"
     },
     "author": "Learning Economy Foundation (www.learningeconomy.io)",
     "license": "MIT",
     "dependencies": {
-        "@learncard/core": "9.4.33",
-        "@learncard/didkit-plugin": "^1.9.13",
-        "@learncard/init": "^2.4.14",
-        "@learncard/lca-api-plugin": "2.0.3",
-        "@learncard/learn-cloud-plugin": "2.3.39",
-        "@learncard/ler-rs-plugin": "0.1.24",
-        "@learncard/linked-claims-plugin": "0.2.33",
-        "@learncard/open-badge-v2-plugin": "1.1.34",
-        "@learncard/render-method-plugin": "5.0.1",
-        "@learncard/holder-continuity": "0.2.16",
-        "@learncard/types": "5.18.3",
-        "@rollup/plugin-json": "^4.1.0",
+        "@learncard/core": "9.4.35",
+        "@learncard/didkit-plugin": "^1.10.0",
+        "@learncard/init": "^2.4.16",
+        "@learncard/lca-api-plugin": "2.0.5",
+        "@learncard/learn-cloud-plugin": "2.3.41",
+        "@learncard/ler-rs-plugin": "0.1.26",
+        "@learncard/linked-claims-plugin": "0.2.35",
+        "@learncard/open-badge-v2-plugin": "1.1.36",
+        "@learncard/render-method-plugin": "7.0.0",
+        "@learncard/holder-continuity": "0.2.18",
+        "@learncard/types": "5.20.0",
         "clipboardy": "^4.0.0",
         "commander": "^9.3.0",
         "figlet": "^1.5.2",
         "gradient-string": "^2.0.1",
-        "pretty-repl": "^3.1.1",
-        "rollup": "^2.80.0",
-        "rollup-plugin-esbuild": "^4.9.1"
+        "pretty-repl": "^3.1.1"
     },
     "devDependencies": {
         "@types/cors": "^2.8.12",
@@ -42,7 +39,10 @@
         "@types/node": "^18.0.0",
         "nodemon": "^2.0.16",
         "ts-node": "^10.8.1",
-        "vitest": "4.1.10"
+        "vitest": "4.1.11",
+        "@rollup/plugin-json": "^4.1.0",
+        "rollup": "^2.80.0",
+        "rollup-plugin-esbuild": "^4.9.1"
     },
     "repository": {
         "type": "git",

package/rollup.config.js

@@ -1,12 +1,34 @@
 import json from '@rollup/plugin-json';
 import esbuild from 'rollup-plugin-esbuild';
 
-const packageJson = require('./package.json');
+import { readFileSync } from 'node:fs';
+
+const packageJson = JSON.parse(readFileSync(new URL('./package.json', import.meta.url), 'utf8'));
 
 export default [
     {
         input: ['src/index.tsx'],
-        output: [{ file: packageJson.bin, format: 'cjs', banner: '#!/usr/bin/env node' }],
-        plugins: [json(), esbuild()],
+        output: [
+            {
+                file: packageJson.bin,
+                format: 'cjs',
+                banner: '#!/usr/bin/env node',
+                inlineDynamicImports: true,
+            },
+        ],
+        plugins: [
+            json(),
+            esbuild(),
+            {
+                name: 'native-webhook-import',
+                renderDynamicImport({ moduleId }) {
+                    // Rollup 2 otherwise emits require(data:...), which Node cannot load.
+                    if (moduleId.endsWith('/src/webhook.ts')) {
+                        return { left: 'import(', right: ')' };
+                    }
+                    return null;
+                },
+            },
+        ],
     },
 ];

package/scripts/embed-snippets.ts

@@ -0,0 +1,25 @@
+import { mkdir, readFile, writeFile } from 'node:fs/promises';
+import { dirname, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const root = resolve(dirname(fileURLToPath(import.meta.url)), '../../..');
+const snippets = {
+    SEND_MJS: 'quickstart/send.mjs',
+    SEND_SH: 'quickstart/send.sh',
+    SEND_FROM_TEMPLATE_MJS: 'quickstart/send-from-template.mjs',
+    WEBHOOK_MJS: 'cli/webhook.mjs',
+    CLAIM_BUTTON_HTML: 'cli/claim-button.html',
+    CREATE_CONTRACT_MJS: 'consentflow/create-contract.mjs',
+    CONSENT_CALLBACK_MJS: 'consentflow/consent-callback.mjs',
+    READ_USER_DATA_MJS: 'consentflow/read-user-data.mjs',
+    ISSUE_THROUGH_CONTRACT_MJS: 'consentflow/issue-through-contract.mjs',
+};
+const lines = await Promise.all(
+    Object.entries(snippets).map(
+        async ([name, file]) =>
+            `export const ${name} = ${JSON.stringify(await readFile(resolve(root, 'docs/snippets', file), 'utf8'))};\n`
+    )
+);
+const output = resolve(root, 'packages/learn-card-cli/src/generated/snippets.ts');
+await mkdir(dirname(output), { recursive: true });
+await writeFile(output, '// Generated from docs/snippets. Do not edit.\n' + lines.join(''));

package/src/consent-contract.ts

@@ -0,0 +1,116 @@
+import {
+    connect,
+    createPrompts,
+    ensureIdentity,
+    ensureProfile,
+    KEYS,
+    loadProject,
+    localizeSnippet,
+    resolveServices,
+    saveProject,
+    STAGING_NETWORK,
+    PRODUCTION_NETWORK,
+    type ProjectOptions,
+    appUrlFor,
+} from './project';
+import {
+    CREATE_CONTRACT_MJS,
+    CONSENT_CALLBACK_MJS,
+    READ_USER_DATA_MJS,
+    ISSUE_THROUGH_CONTRACT_MJS,
+} from './generated/snippets';
+import { writeSnippet } from './snippet-files';
+import { out } from './out';
+
+export const consentUrl = (uri: string, returnTo: string, network: string): string => {
+    const url = new URL('/consent-flow', appUrlFor(network));
+    url.searchParams.set('uri', uri);
+    url.searchParams.set('returnTo', returnTo);
+    return url.toString();
+};
+
+export const runConsentContract = async (
+    options: ProjectOptions & {
+        redirectUrl?: string;
+        description?: string;
+        needsGuardianConsent?: boolean;
+    }
+): Promise<void> => {
+    const project = await loadProject(process.cwd());
+    const returnTo =
+        options.redirectUrl || project.env.RETURN_TO || 'http://localhost:3000/consent-callback';
+    if (!['http:', 'https:'].includes(new URL(returnTo).protocol)) {
+        throw new Error('Redirect URL must use HTTP or HTTPS.');
+    }
+    const identity = await ensureIdentity(project, options);
+    const learnCard = await connect(project, options);
+    await ensureProfile(learnCard, identity, project);
+    let uri = project.env[KEYS.CONTRACT_URI];
+    if (!uri) {
+        const prompts = createPrompts(options.yes);
+        let name: string;
+        try {
+            name = options.name ?? (await prompts.ask('Contract name', identity.displayName));
+        } finally {
+            prompts.close();
+        }
+        const contract = {
+            name,
+            description:
+                options.description ??
+                'Allow us to read your name and achievements and send achievements.',
+            ...(options.needsGuardianConsent ? { needsGuardianConsent: true } : {}),
+            redirectUrl: returnTo,
+            contract: {
+                read: {
+                    personal: { name: { required: false } },
+                    credentials: { categories: { Achievement: { required: false } } },
+                },
+                write: {
+                    personal: {},
+                    credentials: { categories: { Achievement: { required: false } } },
+                },
+            },
+        };
+        uri = await learnCard.invoke.createContract(contract);
+        out.log('Created your consent contract.');
+    } else {
+        out.log('Reusing your saved consent contract.');
+    }
+    await saveProject(project, { [KEYS.CONTRACT_URI]: uri, RETURN_TO: returnTo });
+    const services = resolveServices(project.env, options.network);
+    const files: string[] = [];
+    for (const [file, source] of Object.entries({
+        'create-contract.mjs': CREATE_CONTRACT_MJS,
+        'consent-callback.mjs': CONSENT_CALLBACK_MJS,
+        'read-user-data.mjs': READ_USER_DATA_MJS,
+        'issue-through-contract.mjs': ISSUE_THROUGH_CONTRACT_MJS,
+    })) {
+        // The canonical tutorial uses a destructured SECURE_SEED; normalize only for localization.
+        const localized =
+            services.network === PRODUCTION_NETWORK
+                ? source
+                : localizeSnippet(
+                      source.replaceAll(
+                          'seed: SECURE_SEED, network: true',
+                          'seed: process.env.SECURE_SEED, network: true'
+                      ),
+                      services
+                  );
+        if (await writeSnippet(file, localized)) files.push(`./${file}`);
+    }
+    const contractConsentUrl = consentUrl(uri, returnTo, services.network);
+    out.log(contractConsentUrl);
+    if (![PRODUCTION_NETWORK, STAGING_NETWORK].includes(services.network)) {
+        out.log(
+            'Note: this is a production app URL; use an app connected to your local network to consent.'
+        );
+    }
+    out.log(
+        'The tutorial create-contract.mjs creates a new contract and requires HTTPS; reuse CONTRACT_URI for this dev setup.'
+    );
+    out.log('Read scripts require a verified CONSENT_VP, not a bare DID.');
+    out.log('Next: node --env-file=.env consent-callback.mjs');
+    out.log('See the contract in the app: npx @learncard/cli open contract');
+    out.set({ contractUri: uri, consentUrl: contractConsentUrl, returnTo, files });
+};

package/src/embed.ts

@@ -0,0 +1,102 @@
+import { LCNDomainOrOriginValidator } from '@learncard/types';
+import {
+    connect,
+    ensureIdentity,
+    ensureProfile,
+    KEYS,
+    loadProject,
+    resolveServices,
+    saveProject,
+    type ProjectOptions,
+} from './project';
+import { setupSigning } from './setup-signing';
+import { CLAIM_BUTTON_HTML } from './generated/snippets';
+import { writeSnippet } from './snippet-files';
+import { out } from './out';
+
+export const validateDomains = (domains: string): string[] =>
+    domains.split(',').map(domain => {
+        const result = LCNDomainOrOriginValidator.safeParse(domain.trim());
+        if (!result.success)
+            throw new Error(result.error.format()._errors.join('; ') || result.error.message);
+        return result.data;
+    });
+
+const scriptString = (value: string): string => JSON.stringify(value).replace(/</g, '\\u003c');
+
+export const personalizeClaimButton = (key: string, apiBaseUrl: string): string =>
+    CLAIM_BUTTON_HTML.replace("'PUBLISHABLE_KEY_PLACEHOLDER'", () => scriptString(key)).replace(
+        "'https://network.learncard.com/api'",
+        () => scriptString(apiBaseUrl)
+    );
+
+export const runEmbed = async (
+    options: ProjectOptions & { domains?: string; rotateKey?: boolean }
+): Promise<void> => {
+    const domains = validateDomains(
+        options.domains ?? 'http://localhost:3000,http://localhost:5173'
+    );
+    const project = await loadProject(process.cwd());
+    const identity = await ensureIdentity(project, options);
+    const learnCard = await connect(project, { ...options, lca: true });
+    await ensureProfile(learnCard, identity, project);
+    await setupSigning(project, learnCard);
+    let id = project.env[KEYS.INTEGRATION_ID];
+    const reused = Boolean(id);
+    if (!id) {
+        id = await learnCard.invoke.addIntegration({
+            name: options.name ?? identity.displayName,
+            whitelistedDomains: domains,
+            guideType: 'embed-claim',
+        });
+        // Persist immediately so a later failed read/rotation never duplicates the integration.
+        await saveProject(project, { [KEYS.INTEGRATION_ID]: id });
+    }
+    let integration = await learnCard.invoke.getIntegration(id);
+    if (!integration) throw new Error('Saved integration was not found. Check INTEGRATION_ID.');
+    if (options.rotateKey) {
+        if (!(await learnCard.invoke.updateIntegration(id, { rotatePublishableKey: true }))) {
+            throw new Error('Could not rotate the publishable key.');
+        }
+        integration = await learnCard.invoke.getIntegration(id);
+        if (!integration) throw new Error('Could not read the rotated integration.');
+    }
+    await saveProject(project, {
+        [KEYS.INTEGRATION_ID]: id,
+        [KEYS.PUBLISHABLE_KEY]: integration.publishableKey,
+    });
+    const apiBase = resolveServices(project.env, options.network).network.replace(
+        /\/trpc\/?$/,
+        '/api'
+    );
+    const wroteClaimButton = await writeSnippet(
+        'claim-button.html',
+        personalizeClaimButton(integration.publishableKey, apiBase)
+    );
+    out.log(`Publishable key: ${integration.publishableKey}`);
+    out.log(`Whitelisted origins: ${integration.whitelistedDomains.join(', ')}`);
+    if (options.domains && reused) {
+        out.log(
+            'Existing integrations keep their saved origins; change them in the Developer Portal.'
+        );
+    }
+    if (options.rotateKey)
+        out.log('Update the publishable key in any existing claim-button.html and deployed pages.');
+    const firstDomain = integration.whitelistedDomains[0];
+    const origin = firstDomain?.startsWith('http')
+        ? firstDomain
+        : firstDomain
+          ? `http://${firstDomain}`
+          : undefined;
+    out.log(
+        origin
+            ? `Next: Open claim-button.html from ${origin} (a whitelisted origin), not file://.\nSee the integration in the app: npx @learncard/cli open integration`
+            : 'Next: add a whitelisted origin in the Developer Portal, then serve claim-button.html there, not file://.'
+    );
+    out.set({
+        integrationId: id,
+        publishableKey: integration.publishableKey,
+        whitelistedDomains: integration.whitelistedDomains,
+        files: wroteClaimButton ? ['./claim-button.html'] : [],
+    });
+};