@learncard/idx-plugin 1.1.24 → 1.1.26

package/package.json

@@ -1,61 +1,63 @@
 {
-  "name": "@learncard/idx-plugin",
-  "version": "1.1.24",
-  "description": "",
-  "type": "module",
-  "main": "./dist/index.cjs",
-  "module": "./dist/idx-plugin.esm.js",
-  "exports": {
-    ".": {
-      "import": {
-        "types": "./dist/index.d.ts",
-        "default": "./dist/idx-plugin.esm.js"
-      },
-      "require": {
-        "types": "./dist/index.d.cts",
-        "default": "./dist/index.cjs"
-      }
-    }
-  },
-  "files": [
-    "dist"
-  ],
-  "author": "Learning Economy Foundation (www.learningeconomy.io)",
-  "license": "MIT",
-  "homepage": "https://github.com/learningeconomy/LearnCard/tree/main/packages/plugins/idx/README.md",
-  "repository": {
-    "type": "git",
-    "url": "https://github.com/learningeconomy/LearnCard"
-  },
-  "bugs": {
-    "url": "https://github.com/learningeconomy/LearnCard/issues"
-  },
-  "devDependencies": {
-    "@glazed/types": "0.2.0",
-    "@types/jest": "^29.2.2",
-    "@types/node": "^17.0.31",
-    "aqu": "0.4.3",
-    "esbuild": "^0.27.1",
-    "esbuild-jest": "^0.5.0",
-    "esbuild-plugin-copy": "^1.3.0",
-    "jest": "^29.3.0",
-    "shx": "^0.3.4",
-    "ts-jest": "^29.0.3"
-  },
-  "types": "./dist/index.d.ts",
-  "dependencies": {
-    "@ceramicnetwork/http-client": "2.7.0",
-    "@ceramicnetwork/streamid": "2.7.0",
-    "@glazed/did-datastore": "0.3.2",
-    "@learncard/core": "9.4.24",
-    "@learncard/types": "5.17.4",
-    "@learncard/ceramic-plugin": "^1.1.24"
-  },
-  "sideEffects": false,
-  "scripts": {
-    "build": "node ./scripts/build.mjs && shx cp ./scripts/mixedEntypoint.js ./dist/index.cjs && tsc --p tsconfig.json && shx cp ./dist/index.d.ts ./dist/index.d.cts",
-    "test": "jest --passWithNoTests",
-    "test:watch": "jest --watch",
-    "test:coverage": "jest --silent --ci --coverage --coverageReporters=\"text\" --coverageReporters=\"text-summary\""
-  }
-}
+    "name": "@learncard/idx-plugin",
+    "version": "1.1.26",
+    "description": "",
+    "type": "module",
+    "main": "./dist/index.cjs",
+    "module": "./dist/idx-plugin.esm.js",
+    "exports": {
+        ".": {
+            "development": "./src/index.ts",
+            "import": {
+                "types": "./dist/index.d.ts",
+                "default": "./dist/idx-plugin.esm.js"
+            },
+            "require": {
+                "types": "./dist/index.d.cts",
+                "default": "./dist/index.cjs"
+            }
+        }
+    },
+    "files": [
+        "dist",
+        "src"
+    ],
+    "scripts": {
+        "build": "node ./scripts/build.mjs && shx cp ./scripts/mixedEntypoint.js ./dist/index.cjs && tsc --p tsconfig.json && shx cp ./dist/index.d.ts ./dist/index.d.cts",
+        "test": "jest --passWithNoTests",
+        "test:watch": "jest --watch",
+        "test:coverage": "jest --silent --ci --coverage --coverageReporters=\"text\" --coverageReporters=\"text-summary\""
+    },
+    "author": "Learning Economy Foundation (www.learningeconomy.io)",
+    "license": "MIT",
+    "homepage": "https://github.com/learningeconomy/LearnCard/tree/main/packages/plugins/idx/README.md",
+    "repository": {
+        "type": "git",
+        "url": "https://github.com/learningeconomy/LearnCard"
+    },
+    "bugs": {
+        "url": "https://github.com/learningeconomy/LearnCard/issues"
+    },
+    "devDependencies": {
+        "@glazed/types": "0.2.0",
+        "@types/jest": "^29.2.2",
+        "@types/node": "^17.0.31",
+        "aqu": "0.4.3",
+        "esbuild": "^0.27.1",
+        "esbuild-jest": "^0.5.0",
+        "esbuild-plugin-copy": "^1.3.0",
+        "jest": "^29.3.0",
+        "shx": "^0.3.4",
+        "ts-jest": "^29.0.3"
+    },
+    "types": "./dist/index.d.ts",
+    "dependencies": {
+        "@ceramicnetwork/http-client": "2.7.0",
+        "@ceramicnetwork/streamid": "2.7.0",
+        "@glazed/did-datastore": "0.3.2",
+        "@learncard/ceramic-plugin": "^1.1.26",
+        "@learncard/core": "9.4.26",
+        "@learncard/types": "5.17.5"
+    },
+    "sideEffects": false
+}

package/src/defaults.ts

@@ -0,0 +1,18 @@
+import { IDXArgs } from './types';
+
+export const DEFAULT_IDX_ARGS: IDXArgs = {
+    modelData: {
+        definitions: {
+            MyVerifiableCredentials:
+                'kjzl6cwe1jw14am5tu5hh412s19o4zm8aq3g2lpd6s4paxj2nly2lj4drp3pun2',
+        },
+        schemas: {
+            AchievementVerifiableCredential:
+                'ceramic://k3y52l7qbv1frylibw2725v8gem3hxs1onoh6pvux0szdduugczh0hddxo6qsd6o0',
+            VerifiableCredentialsList:
+                'ceramic://k3y52l7qbv1frxkcwfpyauky3fyl4n44izridy3blvjjzgftis40sk9w8g3remghs',
+        },
+        tiles: {},
+    },
+    credentialAlias: 'MyVerifiableCredentials',
+};

package/src/idx.ts

@@ -0,0 +1,260 @@
+import { DIDDataStore } from '@glazed/did-datastore';
+import { CredentialRecordValidator, VC, CredentialRecord, VCValidator } from '@learncard/types';
+import { LearnCard } from '@learncard/core';
+
+import { streamIdToCeramicURI } from '@learncard/ceramic-plugin';
+
+import {
+    IDXPlugin,
+    CredentialsList,
+    CredentialsListValidator,
+    IDXPluginDependentMethods,
+    IDXArgs,
+    BackwardsCompatCredentialsListValidator,
+} from './types';
+import { DEFAULT_IDX_ARGS } from './defaults';
+
+/**
+ * @group Plugins
+ */
+export const getIDXPlugin = async (
+    learnCard: LearnCard<any, 'read', IDXPluginDependentMethods>,
+    { modelData, credentialAlias }: IDXArgs = DEFAULT_IDX_ARGS
+): Promise<IDXPlugin> => {
+    const ceramic = learnCard.invoke.getCeramicClient();
+
+    const dataStore = new DIDDataStore({ ceramic, model: modelData });
+
+    const getCredentialsListFromIdx = async (alias = credentialAlias): Promise<CredentialsList> => {
+        const list = await dataStore.get(alias);
+
+        if (!list) return { credentials: [] };
+
+        const validationResult = await CredentialsListValidator.spa(list);
+
+        if (validationResult.success) return validationResult.data;
+
+        const backwardsCompatValidationResult = await BackwardsCompatCredentialsListValidator.spa(
+            list
+        );
+
+        if (backwardsCompatValidationResult.success) {
+            const oldCreds = backwardsCompatValidationResult.data.credentials;
+
+            const newCreds = oldCreds.map(cred => {
+                if ('uri' in cred) return cred as CredentialRecord;
+
+                const { title, id, storageType, ...rest } = cred;
+
+                return {
+                    ...rest,
+                    id: title,
+                    uri: `lc:ceramic:${id.replace('ceramic://', '')}`,
+                } as CredentialRecord;
+            });
+
+            const credentialsList = { credentials: newCreds };
+
+            await dataStore.set(credentialAlias, credentialsList);
+
+            return credentialsList;
+        }
+
+        console.error(validationResult.error);
+
+        throw new Error('Invalid credentials list stored in IDX');
+    };
+
+    const removeCredentialFromIdx = async (id: string, alias?: string) => {
+        if (!id) throw new Error('Must provide id to remove');
+
+        if (!alias) alias = credentialAlias;
+
+        const existing = await getCredentialsListFromIdx(alias);
+
+        existing.credentials = existing.credentials.filter(credential => credential.id !== id);
+
+        return dataStore.set(alias, existing);
+    };
+
+    const removeAllCredentialsFromIdx = async (alias?: string) => {
+        if (!alias) alias = credentialAlias;
+
+        return dataStore.set(alias, { credentials: [] });
+    };
+
+    const addCredentialInIdx = async <T extends Record<string, any>>(
+        _record: CredentialRecord<T>
+    ) => {
+        const record = await CredentialRecordValidator.parseAsync(_record);
+
+        if (!record) throw new Error('record is required');
+
+        if (!record.uri) throw Error('No URI provided');
+
+        // Make sure URI can be resolved
+        await learnCard.read.get(record.uri);
+
+        const existing = await getCredentialsListFromIdx(credentialAlias);
+
+        const indexOfExistingCredential = existing.credentials.findIndex(credential => {
+            return credential.id === record.id;
+        });
+
+        if (indexOfExistingCredential > -1) {
+            existing.credentials[indexOfExistingCredential] = record;
+        } else existing.credentials.push(record);
+
+        return streamIdToCeramicURI(await dataStore.set(credentialAlias, existing));
+    };
+
+    const addCredentialsInIdx = async <T extends Record<string, any>>(
+        _records: CredentialRecord<T>[]
+    ) => {
+        const records = CredentialRecordValidator.array().parse(_records);
+
+        const existing = await getCredentialsListFromIdx(credentialAlias);
+
+        await Promise.all(
+            records.map(async record => {
+                // Make sure URI can be resolved
+                await learnCard.read.get(record.uri);
+
+                const indexOfExistingCredential = existing.credentials.findIndex(credential => {
+                    return credential.id === record.id;
+                });
+
+                if (indexOfExistingCredential > -1) {
+                    existing.credentials[indexOfExistingCredential] = record;
+                } else existing.credentials.push(record);
+            })
+        );
+
+        return streamIdToCeramicURI(await dataStore.set(credentialAlias, existing));
+    };
+
+    return {
+        name: 'IDX',
+        displayName: 'IDX',
+        description: 'Stores a bespoke index of credentials for an individual based on their did',
+        index: {
+            get: async _learnCard => {
+                _learnCard.debug?.('learnCard.index.IDX.get');
+
+                const list = await getCredentialsListFromIdx();
+
+                return list.credentials;
+            },
+            add: async (_learnCard, record) => {
+                _learnCard.debug?.('learnCard.index.IDX.add');
+
+                try {
+                    await addCredentialInIdx(record);
+
+                    return true;
+                } catch (error) {
+                    console.error('Error adding credential with IDX:', error);
+
+                    return false;
+                }
+            },
+            addMany: async (_learnCard, records) => {
+                _learnCard.debug?.('learnCard.index.IDX.add');
+
+                try {
+                    await addCredentialsInIdx(records);
+
+                    return true;
+                } catch (error) {
+                    console.error('Error adding credential with IDX:', error);
+
+                    return false;
+                }
+            },
+            update: async _learnCard => {
+                _learnCard.debug?.('learnCard.index.IDX.update');
+
+                // TODO: Implement update
+                return false;
+            },
+            remove: async (_learnCard, id) => {
+                _learnCard.debug?.('learnCard.index.IDX.remove');
+
+                try {
+                    await removeCredentialFromIdx(id);
+
+                    return true;
+                } catch (error) {
+                    console.error('Error removing credential from IDX:', error);
+
+                    return false;
+                }
+            },
+            removeAll: async _learnCard => {
+                _learnCard.debug?.('learnCard.index.IDX.removeAll');
+
+                try {
+                    await removeAllCredentialsFromIdx();
+
+                    return true;
+                } catch (error) {
+                    console.error('Error removing credentials from IDX:', error);
+
+                    return false;
+                }
+            },
+        },
+        methods: {
+            getCredentialsListFromIdx: async (_learnCard, alias = credentialAlias) =>
+                (await getCredentialsListFromIdx(alias)).credentials,
+            getVerifiableCredentialFromIdx: async (_learnCard, id) => {
+                const credentialList = await getCredentialsListFromIdx();
+                const credential = credentialList?.credentials?.find(cred => cred?.id === id);
+
+                const result = _learnCard.read.get(credential?.uri);
+
+                const validationResult = await VCValidator.safeParseAsync(result);
+
+                return validationResult.success ? validationResult.data : undefined;
+            },
+            getVerifiableCredentialsFromIdx: async _learnCard => {
+                const credentialList = await getCredentialsListFromIdx();
+                const uris = credentialList?.credentials?.map(credential => credential?.uri) ?? [];
+
+                return (await Promise.all(uris.map(async uri => _learnCard.read.get(uri)))).filter(
+                    (vc): vc is VC => !!vc
+                );
+            },
+            addVerifiableCredentialInIdx: async (_learnCard, idxCredential) => {
+                const record = CredentialRecordValidator.parse(idxCredential);
+
+                if (!record) throw new Error('record is required');
+
+                if (!record.uri) throw Error('No URI provided');
+
+                // Make sure URI can be resolved
+                await _learnCard.read.get(record.uri);
+
+                const existing = await getCredentialsListFromIdx(credentialAlias);
+
+                const indexOfExistingCredential = existing.credentials.findIndex(credential => {
+                    return credential.id === record.id;
+                });
+
+                if (indexOfExistingCredential > -1) {
+                    existing.credentials[indexOfExistingCredential] = record;
+                } else existing.credentials.push(record);
+
+                return streamIdToCeramicURI(await dataStore.set(credentialAlias, existing));
+            },
+            removeVerifiableCredentialInIdx: async (_learnCard, id) => {
+                return removeCredentialFromIdx(id);
+            },
+            removeAllVerifiableCredentialsInIdx: async () => {
+                return removeAllCredentialsFromIdx();
+            },
+            getIDXIndex: async () => dataStore.get(credentialAlias),
+            setIDXIndex: async (_learnCard, index) => dataStore.set(credentialAlias, index),
+        },
+    };
+};

package/src/index.ts

@@ -0,0 +1,5 @@
+import { getIDXPlugin } from './idx';
+export { getIDXPlugin } from './idx';
+export * from './types';
+
+export default getIDXPlugin;

package/src/types.ts

@@ -0,0 +1,88 @@
+import { ModelAliases } from '@glazed/types';
+import { z } from 'zod';
+import { StreamID } from '@ceramicnetwork/streamid';
+import { Plugin } from '@learncard/core';
+import { VC, CredentialRecord, CredentialRecordValidator } from '@learncard/types';
+import { CeramicClient } from '@ceramicnetwork/http-client';
+
+/** @group IDXPlugin */
+export type IDXIndexObject<
+    IDXMetadata extends Record<string, any>,
+    Metadata extends Record<string, any>
+> = {
+    credentials: CredentialRecord<Metadata>[];
+} & IDXMetadata;
+
+/** @group IDXPlugin */
+export type IDXArgs = {
+    modelData: ModelAliases;
+    credentialAlias: string;
+};
+
+/** @group IDXPlugin */
+export type IDXPluginMethods = {
+    getCredentialsListFromIdx: <Metadata extends Record<string, any> = Record<never, never>>(
+        alias?: string
+    ) => Promise<CredentialRecord<Metadata>[]>;
+    getVerifiableCredentialFromIdx: (id: string) => Promise<VC | undefined>;
+    getVerifiableCredentialsFromIdx: () => Promise<VC[]>;
+    addVerifiableCredentialInIdx: <Metadata extends Record<string, any> = Record<never, never>>(
+        cred: CredentialRecord<Metadata>
+    ) => Promise<string>;
+    removeVerifiableCredentialInIdx: (title: string) => Promise<StreamID>;
+    removeAllVerifiableCredentialsInIdx: () => Promise<StreamID>;
+    getIDXIndex: <
+        IDXMetadata extends Record<string, any>,
+        Metadata extends Record<string, any>
+    >() => Promise<IDXIndexObject<IDXMetadata, Metadata> | null>;
+    setIDXIndex: <IDXMetadata extends Record<string, any>, Metadata extends Record<string, any>>(
+        index: IDXIndexObject<IDXMetadata, Metadata>
+    ) => Promise<StreamID>;
+};
+
+/** @group IDXPlugin */
+export type IDXPluginDependentMethods = {
+    getCeramicClient: () => CeramicClient;
+};
+
+/** @group IDXPlugin */
+export type CredentialsList<Metadata extends Record<string, any> = Record<never, never>> = {
+    credentials: Array<CredentialRecord<Metadata>>;
+};
+
+/** @group IDXPlugin */
+export const CredentialsListValidator: z.ZodType<CredentialsList> = z
+    .object({
+        credentials: CredentialRecordValidator.array(),
+    })
+    .catchall(z.any());
+
+/** @group IDXPlugin */
+export type IDXPlugin = Plugin<'IDX', 'index', IDXPluginMethods, 'read', IDXPluginDependentMethods>;
+
+// Below types are temporary! They will be removed in the future when we are confident that everyone
+// has moved on to the new schema
+
+/** @group IDXPlugin */
+export type BackwardsCompatIDXCredential<
+    Metadata extends Record<string, any> = Record<never, never>
+> = { [key: string]: any; id: string; title: string; storageType?: 'ceramic' } & Metadata;
+
+/** @group IDXPlugin */
+export const BackwardsCompatIDXCredentialValidator: z.ZodType<BackwardsCompatIDXCredential> = z
+    .object({ id: z.string(), title: z.string(), storageType: z.literal('ceramic').optional() })
+    .catchall(z.any());
+
+/** @group IDXPlugin */
+export type BackwardsCompatCredentialsList<
+    Metadata extends Record<string, any> = Record<never, never>
+> = {
+    credentials: Array<CredentialRecord<Metadata> | BackwardsCompatIDXCredential<Metadata>>;
+};
+
+/** @group IDXPlugin */
+export const BackwardsCompatCredentialsListValidator: z.ZodType<BackwardsCompatCredentialsList> = z
+    .object({
+        credentials: CredentialRecordValidator.or(BackwardsCompatIDXCredentialValidator).array(),
+    })
+    .strict();