@learncard/render-method-plugin 3.0.3 → 3.0.5

package/src/types.ts

@@ -0,0 +1,119 @@
+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 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>
+>;

package/LICENSE

@@ -1,21 +0,0 @@
-MIT License
-
-Copyright (c) 2025 Learning Economy Foundation <sdk@learningeconomy.io>
-
-Permission is hereby granted, free of charge, to any person obtaining a copy
-of this software and associated documentation files (the "Software"), to deal
-in the Software without restriction, including without limitation the rights
-to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
-copies of the Software, and to permit persons to whom the Software is
-furnished to do so, subject to the following conditions:
-
-The above copyright notice and this permission notice shall be included in all
-copies or substantial portions of the Software.
-
-THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
-IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
-FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
-AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
-LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
-OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
-SOFTWARE.