@learncard/render-method-plugin 2.0.0

package/dist/types.d.ts

@@ -0,0 +1,102 @@
+import { Plugin, LearnCard } from '@learncard/core';
+import { UnsignedVC, VC, RenderMethod, TemplateRenderMethod } from '@learncard/types';
+/**
+ * JSON-LD context for W3C `renderMethod`.
+ *
+ * ⚠️ DRAFT CONTEXT WARNING
+ * This URL points to a community-group draft hosted on Digital Bazaar's GitHub Pages, not a
+ * finalized W3C TR. The `v2rc2` suffix means "v2, release candidate 2".
+ *
+ * Risks of issuing VCs that reference this URL in their `@context`:
+ * - URL could move, be renamed, or 404 — JSON-LD context resolution would fail at verification time.
+ * - Term definitions could change between rc2 and a final spec, breaking interpretation.
+ * - Not statically cached by DidKit — verification incurs a network fetch.
+ *
+ * Mitigation plan (not yet implemented):
+ * - Bundle the context locally (see `packages/learn-card-contexts/` for the prior pattern).
+ * - Migrate to a stable W3C TR context URL when the spec finalizes.
+ *
+ * Tracking: https://www.w3.org/TR/vc-render-method/ (when published).
+ */
+export declare const RENDER_METHOD_CONTEXT = "https://digitalbazaar.github.io/vc-render-method-context/contexts/v2rc2.jsonld";
+/**
+ * Config for building a render method. Exactly one of `templateId` or `templateValue` must be
+ * provided — the discriminated union enforces this at compile time.
+ *
+ * - `templateId`: HTTPS URL of a hosted SVG Mustache template (only `http://` or `https://` is accepted).
+ * - `templateValue`: Inline SVG Mustache content (URL-encoded into a `data:image/svg+xml,` URI).
+ * - `renderProperty`: Optional JSON Pointer paths (RFC 6901) scoping which VC fields are exposed
+ *   to the template.
+ */
+export type AttachRenderMethodConfig = {
+    templateId: string;
+    templateValue?: never;
+    renderProperty?: string[];
+} | {
+    templateValue: string;
+    templateId?: never;
+    renderProperty?: string[];
+};
+type AnyCredential = VC | UnsignedVC;
+export type RenderMethodPluginMethods = {
+    /**
+     * Attaches a `TemplateRenderMethod` to an unsigned VC and injects the render-method JSON-LD
+     * context. Merges with any existing `renderMethod` entries.
+     *
+     * **Opt-in:** returns the VC unchanged if `config` is omitted. Callers must explicitly choose
+     * a template. Pass `{ templateId: DEFAULT_TEMPLATE_ID }` to use the default hosted LearnCard
+     * template.
+     *
+     * @throws if `templateId` is not an http(s) URL, or if `templateValue` is empty.
+     */
+    attachRenderMethod: (vc: UnsignedVC, config?: AttachRenderMethodConfig) => UnsignedVC;
+    /**
+     * Builds a `TemplateRenderMethod` descriptor without mutating a VC. Useful when callers need
+     * to compose the descriptor independently.
+     *
+     * @throws if `templateId` is not an http(s) URL, or if `templateValue` is empty.
+     */
+    buildTemplateRenderMethod: (config: AttachRenderMethodConfig) => TemplateRenderMethod;
+    /**
+     * Returns all `renderMethod` entries on a VC, normalizing single-object form to an array and
+     * unwrapping `CertifiedBoostCredential`. Entries are NOT validated — apply a type guard via
+     * `findRenderMethod` / `findRenderMethods` for selection.
+     */
+    getRenderMethods: (vc: AnyCredential) => RenderMethod[];
+    /**
+     * First `renderMethod` matching a type-guard predicate, or `null`. The predicate's narrowed
+     * type is returned, so callers using `isSvgMustacheRenderMethod` get back a
+     * `TemplateRenderMethod` (validated against the Zod schema).
+     */
+    findRenderMethod: <T extends RenderMethod = RenderMethod>(vc: AnyCredential, predicate: (rm: RenderMethod) => rm is T) => T | null;
+    /** Like `findRenderMethod`, but returns every matching entry. */
+    findRenderMethods: <T extends RenderMethod = RenderMethod>(vc: AnyCredential, predicate: (rm: RenderMethod) => rm is T) => T[];
+    /**
+     * First `TemplateRenderMethod` on a VC whose `renderSuite` matches the given suite name (or
+     * any of the names in an array — useful for capability negotiation). Returns the Zod-parsed
+     * shape, or `null` if no entry matches.
+     */
+    findTemplateRenderMethod: (vc: AnyCredential, suite: string | readonly string[]) => TemplateRenderMethod | null;
+    /** Like `findTemplateRenderMethod`, but returns every matching entry. */
+    findTemplateRenderMethods: (vc: AnyCredential, suite: string | readonly string[]) => TemplateRenderMethod[];
+    /**
+     * Convenience: the first svg-mustache `TemplateRenderMethod` on a VC, or `null`. Equivalent
+     * to `findTemplateRenderMethod(vc, 'svg-mustache')`.
+     */
+    getSvgMustacheRenderMethod: (vc: AnyCredential) => TemplateRenderMethod | null;
+    /**
+     * Portable Mustache render-data context for a VC. Spreads the credential at the top level and
+     * adds `vc`, `credential`, `credentialSubjects` aliases so templates authored against any
+     * common shape work uniformly. When `renderProperty` is provided (RFC 6901 JSON Pointers),
+     * those values are overlaid at their pointer paths.
+     */
+    buildRenderData: (vc: AnyCredential, renderProperty?: string[]) => Record<string, unknown>;
+};
+/**
+ * This plugin is stateless and has no required dependent methods or control planes. It accepts
+ * any wallet stack.
+ */
+export type RenderMethodDependentLearnCard = LearnCard<any[]>;
+export type RenderMethodPlugin = Plugin<'Render Method', never, RenderMethodPluginMethods, never, Record<never, never>>;
+export {};
+//# sourceMappingURL=types.d.ts.map

package/dist/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,iBAAiB,CAAC;AACpD,OAAO,EAAE,UAAU,EAAE,EAAE,EAAE,YAAY,EAAE,oBAAoB,EAAE,MAAM,kBAAkB,CAAC;AAEtF;;;;;;;;;;;;;;;;;GAiBG;AACH,eAAO,MAAM,qBAAqB,mFACkD,CAAC;AAErF;;;;;;;;GAQG;AACH,MAAM,MAAM,wBAAwB,GAC9B;IAAE,UAAU,EAAE,MAAM,CAAC;IAAC,aAAa,CAAC,EAAE,KAAK,CAAC;IAAC,cAAc,CAAC,EAAE,MAAM,EAAE,CAAA;CAAE,GACxE;IAAE,aAAa,EAAE,MAAM,CAAC;IAAC,UAAU,CAAC,EAAE,KAAK,CAAC;IAAC,cAAc,CAAC,EAAE,MAAM,EAAE,CAAA;CAAE,CAAC;AAE/E,KAAK,aAAa,GAAG,EAAE,GAAG,UAAU,CAAC;AAErC,MAAM,MAAM,yBAAyB,GAAG;IACpC;;;;;;;;;OASG;IACH,kBAAkB,EAAE,CAAC,EAAE,EAAE,UAAU,EAAE,MAAM,CAAC,EAAE,wBAAwB,KAAK,UAAU,CAAC;IACtF;;;;;OAKG;IACH,yBAAyB,EAAE,CAAC,MAAM,EAAE,wBAAwB,KAAK,oBAAoB,CAAC;IACtF;;;;OAIG;IACH,gBAAgB,EAAE,CAAC,EAAE,EAAE,aAAa,KAAK,YAAY,EAAE,CAAC;IACxD;;;;OAIG;IACH,gBAAgB,EAAE,CAAC,CAAC,SAAS,YAAY,GAAG,YAAY,EACpD,EAAE,EAAE,aAAa,EACjB,SAAS,EAAE,CAAC,EAAE,EAAE,YAAY,KAAK,EAAE,IAAI,CAAC,KACvC,CAAC,GAAG,IAAI,CAAC;IACd,iEAAiE;IACjE,iBAAiB,EAAE,CAAC,CAAC,SAAS,YAAY,GAAG,YAAY,EACrD,EAAE,EAAE,aAAa,EACjB,SAAS,EAAE,CAAC,EAAE,EAAE,YAAY,KAAK,EAAE,IAAI,CAAC,KACvC,CAAC,EAAE,CAAC;IACT;;;;OAIG;IACH,wBAAwB,EAAE,CACtB,EAAE,EAAE,aAAa,EACjB,KAAK,EAAE,MAAM,GAAG,SAAS,MAAM,EAAE,KAChC,oBAAoB,GAAG,IAAI,CAAC;IACjC,yEAAyE;IACzE,yBAAyB,EAAE,CACvB,EAAE,EAAE,aAAa,EACjB,KAAK,EAAE,MAAM,GAAG,SAAS,MAAM,EAAE,KAChC,oBAAoB,EAAE,CAAC;IAC5B;;;OAGG;IACH,0BAA0B,EAAE,CAAC,EAAE,EAAE,aAAa,KAAK,oBAAoB,GAAG,IAAI,CAAC;IAC/E;;;;;OAKG;IACH,eAAe,EAAE,CAAC,EAAE,EAAE,aAAa,EAAE,cAAc,CAAC,EAAE,MAAM,EAAE,KAAK,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CAC9F,CAAC;AAEF;;;GAGG;AACH,MAAM,MAAM,8BAA8B,GAAG,SAAS,CAAC,GAAG,EAAE,CAAC,CAAC;AAE9D,MAAM,MAAM,kBAAkB,GAAG,MAAM,CACnC,eAAe,EACf,KAAK,EACL,yBAAyB,EACzB,KAAK,EACL,MAAM,CAAC,KAAK,EAAE,KAAK,CAAC,CACvB,CAAC"}

package/package.json

@@ -0,0 +1,60 @@
+{
+  "name": "@learncard/render-method-plugin",
+  "version": "2.0.0",
+  "description": "LearnCard plugin for attaching W3C renderMethod to Verifiable Credentials",
+  "main": "./dist/index.js",
+  "module": "./dist/render-method-plugin.esm.js",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "module": "./dist/render-method-plugin.esm.js",
+      "import": "./dist/render-method-plugin.esm.js",
+      "require": "./dist/index.js",
+      "default": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "author": "Learning Economy Foundation (www.learningeconomy.io)",
+  "license": "MIT",
+  "homepage": "https://github.com/learningeconomy/LearnCard/tree/main/packages/plugins/render-method/README.md",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/learningeconomy/LearnCard.git"
+  },
+  "bugs": {
+    "url": "https://github.com/learningeconomy/LearnCard/issues"
+  },
+  "devDependencies": {
+    "@types/jest": "^29.2.2",
+    "@types/node": "^17.0.31",
+    "aqu": "0.4.3",
+    "esbuild": "^0.14.38",
+    "esbuild-jest": "^0.5.0",
+    "esbuild-plugin-copy": "^1.3.0",
+    "jest": "^29.3.0",
+    "rimraf": "^3.0.2",
+    "shx": "^0.3.4",
+    "ts-jest": "^29.0.3",
+    "@learncard/core": "9.4.19",
+    "@learncard/helpers": "1.3.1",
+    "@learncard/types": "5.16.0"
+  },
+  "peerDependencies": {
+    "@learncard/core": "9.4.19",
+    "@learncard/helpers": "1.3.1",
+    "@learncard/types": "5.16.0"
+  },
+  "dependencies": {
+    "@learncard/helpers": "1.3.1"
+  },
+  "types": "./dist/index.d.ts",
+  "sideEffects": false,
+  "scripts": {
+    "build": "node ./scripts/build.mjs && shx cp ./scripts/mixedEntrypoint.js ./dist/index.js && tsc --p tsconfig.json",
+    "test": "jest --passWithNoTests",
+    "test:watch": "jest --watch",
+    "test:coverage": "jest --silent --ci --coverage --coverageReporters=\"text\" --coverageReporters=\"text-summary\""
+  }
+}