@learncard/core 9.4.24 → 9.4.26

package/src/types/planes.ts

@@ -0,0 +1,212 @@
+import {
+    CredentialRecord,
+    StoredCredentialEnvelope,
+    VC,
+    VP,
+    JWKWithPrivateKey,
+} from '@learncard/types';
+import { Query } from 'sift';
+import { Plugin } from './wallet';
+import { OmitNevers } from './helpers';
+import { DeepPartial } from './utilities';
+
+export type CacheStrategy = 'cache-only' | 'cache-first' | 'skip-cache';
+
+export type PlaneOptions = {
+    cache?: CacheStrategy;
+};
+
+export type ControlPlane = 'read' | 'store' | 'index' | 'cache' | 'id' | 'context';
+
+export type FilterForPlane<Plugins extends Plugin[], Plane extends ControlPlane> = [
+    Plugins
+] extends [1 & Plugins]
+    ? any
+    : {
+          [Index in keyof Plugins]: undefined extends Plugins[Index][Plane]
+              ? never
+              : Plugins[Index]['name'];
+      }[number];
+
+export type GetPlanesForPlugins<Plugins extends Plugin[]> = any[] extends Plugins
+    ? never
+    : {
+          [Index in keyof Plugins]: {
+              [Key in ControlPlane]: undefined extends Plugins[Index][Key] ? never : Key;
+          }[ControlPlane];
+      }[number];
+
+export type GetPlaneProviders<
+    Plugins extends Plugin[],
+    Plane extends ControlPlane
+> = any[] extends Plugins
+    ? any
+    : {
+          [Index in keyof Plugins]: undefined extends Plugins[Index][Plane]
+              ? never
+              : OmitNevers<{
+                    [Name in Plugins[number]['name']]: Name extends Plugins[Index]['name']
+                        ? { name: Name; displayName?: string; description?: string }
+                        : never;
+                }>;
+      }[number];
+
+// --- Read --- \\
+
+export type ReadPlane = {
+    get: (
+        uri?: string,
+        options?: PlaneOptions
+    ) => Promise<VC | VP | StoredCredentialEnvelope | undefined>;
+};
+
+export type PluginReadPlane = ReadPlane;
+
+export type LearnCardReadPlane<Plugins extends Plugin[]> = ReadPlane & {
+    providers: GetPlaneProviders<Plugins, 'read'>;
+};
+
+// --- Store --- \\
+
+export type EncryptionParams = {
+    recipients: string[];
+};
+
+export type StorePlane = {
+    upload: (vc: VC | VP | StoredCredentialEnvelope, options?: PlaneOptions) => Promise<string>;
+    uploadMany?: (
+        vcs: Array<VC | VP | StoredCredentialEnvelope>,
+        options?: PlaneOptions
+    ) => Promise<string[]>;
+    uploadEncrypted?: (
+        vc: VC | VP | StoredCredentialEnvelope,
+        params?: EncryptionParams,
+        options?: PlaneOptions
+    ) => Promise<string>;
+    delete?: (uri: string, options?: PlaneOptions) => Promise<boolean>;
+};
+
+export type PluginStorePlane = StorePlane;
+
+export type LearnCardStorePlane<Plugins extends Plugin[]> = Record<
+    FilterForPlane<Plugins, 'store'>,
+    StorePlane
+> & {
+    providers: GetPlaneProviders<Plugins, 'store'>;
+};
+
+// --- Index --- \\
+
+export type IndexPlane = {
+    get: <Metadata extends Record<string, any> = Record<never, never>>(
+        query?: Partial<Query<CredentialRecord<Metadata>>>,
+        options?: PlaneOptions
+    ) => Promise<CredentialRecord<Metadata>[]>;
+    getPage?: <Metadata extends Record<string, any> = Record<never, never>>(
+        query?: Partial<Query<CredentialRecord<Metadata>>>,
+        paginationOptions?: { limit?: number; cursor?: string; sort?: string },
+        options?: PlaneOptions
+    ) => Promise<{ records: CredentialRecord<Metadata>[]; hasMore: boolean; cursor?: string }>;
+    getCount?: <Metadata extends Record<string, any> = Record<never, never>>(
+        query?: Partial<Query<CredentialRecord<Metadata>>>,
+        options?: PlaneOptions
+    ) => Promise<number>;
+    add: <Metadata extends Record<string, any> = Record<never, never>>(
+        record: CredentialRecord<Metadata>,
+        options?: PlaneOptions
+    ) => Promise<boolean>;
+    addMany?: <Metadata extends Record<string, any> = Record<never, never>>(
+        records: CredentialRecord<Metadata>[],
+        options?: PlaneOptions
+    ) => Promise<boolean>;
+    update: <Metadata extends Record<string, any> = Record<never, never>>(
+        id: string,
+        updates: DeepPartial<CredentialRecord<Metadata>>,
+        options?: PlaneOptions
+    ) => Promise<boolean>;
+    remove: (id: string, options?: PlaneOptions) => Promise<boolean>;
+    removeAll?: (options?: PlaneOptions) => Promise<boolean>;
+};
+
+export type PluginIndexPlane = IndexPlane;
+
+export type LearnCardIndexPlane<Plugins extends Plugin[]> = {
+    all: Pick<IndexPlane, 'get'>;
+    providers: GetPlaneProviders<Plugins, 'index'>;
+} & Record<FilterForPlane<Plugins, 'index'>, IndexPlane>;
+
+// --- Cache --- \\
+
+export type CachePlane = {
+    getIndex: <Metadata extends Record<string, any> = Record<never, never>>(
+        name: string,
+        query: Partial<Query<CredentialRecord<Metadata>>>
+    ) => Promise<CredentialRecord<Metadata>[] | undefined>;
+    setIndex: <Metadata extends Record<string, any> = Record<never, never>>(
+        name: string,
+        query: Partial<Query<CredentialRecord<Metadata>>>,
+        value: CredentialRecord<Metadata>[]
+    ) => Promise<boolean>;
+    getIndexPage: <Metadata extends Record<string, any> = Record<never, never>>(
+        name: string,
+        query: Partial<Query<CredentialRecord<Metadata>>>,
+        paginationOptions?: { limit?: number; cursor?: string; sort?: string }
+    ) => Promise<
+        { records: CredentialRecord<Metadata>[]; hasMore: boolean; cursor?: string } | undefined
+    >;
+    setIndexPage: <Metadata extends Record<string, any> = Record<never, never>>(
+        name: string,
+        query: Partial<Query<CredentialRecord<Metadata>>>,
+        value: { records: CredentialRecord<Metadata>[]; hasMore: boolean; cursor?: string },
+        paginationOptions?: { limit?: number; cursor?: string }
+    ) => Promise<boolean>;
+    getIndexCount?: <Metadata extends Record<string, any> = Record<never, never>>(
+        name: string,
+        query: Partial<Query<CredentialRecord<Metadata>>>
+    ) => Promise<number | undefined>;
+    setIndexCount?: <Metadata extends Record<string, any> = Record<never, never>>(
+        name: string,
+        query: Partial<Query<CredentialRecord<Metadata>>>,
+        value: number
+    ) => Promise<boolean>;
+    flushIndex: () => Promise<boolean>;
+    getVc: (uri: string) => Promise<VC | VP | StoredCredentialEnvelope | undefined>;
+    setVc: (uri: string, value: VC | VP | StoredCredentialEnvelope | undefined) => Promise<boolean>;
+    flushVc: () => Promise<boolean>;
+};
+export type PluginCachePlane = CachePlane;
+
+export type LearnCardCachePlane<Plugins extends Plugin[]> = CachePlane & {
+    providers: GetPlaneProviders<Plugins, 'cache'>;
+};
+
+// --- Identity --- \\
+
+export type IdPlane = {
+    did: (method?: string, options?: PlaneOptions) => string;
+    keypair: (algorithm?: string, options?: PlaneOptions) => JWKWithPrivateKey;
+};
+
+export type PluginIdPlane = IdPlane;
+
+export type LearnCardIdPlane<Plugins extends Plugin[]> = IdPlane & {
+    providers: GetPlaneProviders<Plugins, 'id'>;
+};
+
+// --- Contexts --- \\
+
+export type ContextPlane = {
+    resolveDocument: (
+        uri: string,
+        allowRemote?: boolean
+    ) => Promise<Record<string, any> | undefined>;
+};
+
+export type PluginContextPlane = {
+    resolveStaticDocument: (uri: string) => Promise<Record<string, any> | undefined>;
+    resolveRemoteDocument?: (uri: string) => Promise<Record<string, any> | undefined>;
+};
+
+export type LearnCardContextPlane<Plugins extends Plugin[]> = ContextPlane & {
+    providers: GetPlaneProviders<Plugins, 'context'>;
+};

package/src/types/utilities.ts

@@ -0,0 +1,39 @@
+/** @group Utility Types */
+export type Tail<T extends any[]> = T extends [any, ...infer R] ? R : never;
+
+/** @group Utility Types */
+export type Last<T extends any[]> = T extends [...any[], infer R] ? R : never;
+
+/** @group Utility Types */
+export type RemoveLast<T extends any[]> = T extends [...infer R, any] ? R : [];
+
+/** @group Utility Types */
+export type RemoveFirstArg<T extends (...args: any[]) => any> = (
+    args: Tail<Parameters<T>>
+) => ReturnType<T>;
+
+/** @group Utility Types */
+export type RemoveLastArg<T extends (...args: any[]) => any> = (
+    args: RemoveLast<Parameters<T>>
+) => ReturnType<T>;
+
+/** @group Utility Types */
+export type UnionToIntersection<U> = (U extends any ? (k: U) => void : never) extends (
+    k: infer I
+) => void
+    ? I
+    : never;
+
+/** @group Utility Types */
+export type MergeObjects<Objects extends Record<string, any>[]> = undefined extends Objects[2]
+    ? Omit<Objects[0], keyof Objects[1]> & Objects[1]
+    : Omit<MergeObjects<RemoveLast<Objects>>, keyof Last<Objects>> & Last<Objects>;
+
+/** @group Utility Types */
+export type DeepPartial<T> = T extends object
+    ? {
+        [P in keyof T]?: DeepPartial<T[P]>;
+    }
+    : T;
+
+export type IsAnyOrNever<T> = [T] extends [1 & T] ? true : false;

package/src/types/wallet.ts

@@ -0,0 +1,176 @@
+import {
+    ControlPlane,
+    GetPlanesForPlugins,
+    PluginReadPlane,
+    PluginStorePlane,
+    PluginIndexPlane,
+    PluginCachePlane,
+    PluginIdPlane,
+    PluginContextPlane,
+    LearnCardReadPlane,
+    LearnCardStorePlane,
+    LearnCardIndexPlane,
+    LearnCardCachePlane,
+    LearnCardIdPlane,
+    LearnCardContextPlane,
+} from './planes';
+import { UnionToIntersection, MergeObjects, IsAnyOrNever } from './utilities';
+
+export type GenerateLearnCard<
+    NewControlPlanes extends ControlPlane = never,
+    NewMethods extends Record<string, (...args: any[]) => any> = Record<never, never>,
+    ControlPlanes extends ControlPlane = never,
+    Methods extends Record<string, (...args: any[]) => any> = Record<never, never>
+> = LearnCard<
+    any,
+    IsAnyOrNever<ControlPlanes> extends true
+    ? NewControlPlanes
+    : IsAnyOrNever<NewControlPlanes> extends true
+    ? ControlPlanes
+    : ControlPlanes | NewControlPlanes,
+    NewMethods & Methods
+>;
+
+export type AddImplicitLearnCardArgument<
+    Functions extends Record<string, (...args: any[]) => any> = Record<never, never>,
+    ControlPlanes extends ControlPlane = never,
+    Methods extends Record<string, (...args: any[]) => any> = Record<never, never>,
+    DependentControlPlanes extends ControlPlane = never,
+    DependentMethods extends Record<string, (...args: any[]) => any> = Record<never, never>
+> = {
+        [Key in keyof Functions]: <
+            T extends GenerateLearnCard<
+                ControlPlanes,
+                Methods,
+                DependentControlPlanes,
+                DependentMethods
+            >
+        >(
+            learnCard: T,
+            ...args: Parameters<Functions[Key]>
+        ) => ReturnType<Functions[Key]>;
+    };
+
+/** @group Universal Wallets */
+export type GetPluginMethods<Plugins extends Plugin[]> = undefined extends Plugins[1]
+    ? NonNullable<Plugins[0]['_methods']>
+    : UnionToIntersection<
+        NonNullable<
+            MergeObjects<{ [Key in keyof Plugins]: NonNullable<Plugins[Key]['_methods']> }>
+        >
+    >;
+
+/** @group Universal Wallets */
+export type Plugin<
+    Name extends string = string,
+    ControlPlanes extends ControlPlane = any,
+    Methods extends Record<string, (...args: any[]) => any> = Record<never, never>,
+    DependentControlPlanes extends ControlPlane = never,
+    DependentMethods extends Record<string, (...args: any[]) => any> = Record<never, never>
+> = {
+    name: Name;
+    displayName?: string;
+    description?: string;
+    methods: AddImplicitLearnCardArgument<
+        Methods,
+        ControlPlanes,
+        Methods,
+        DependentControlPlanes,
+        DependentMethods
+    >;
+    _methods?: Methods;
+    read?: {};
+    store?: {};
+    index?: {};
+    cache?: {};
+    id?: {};
+    context?: {};
+} & (IsAnyOrNever<ControlPlanes> extends true
+    ? {}
+    : ('read' extends ControlPlanes
+        ? {
+            read: AddImplicitLearnCardArgument<
+                PluginReadPlane,
+                ControlPlanes,
+                Methods,
+                DependentControlPlanes,
+                DependentMethods
+            >;
+        }
+        : {}) &
+    ('store' extends ControlPlanes
+        ? {
+            store: AddImplicitLearnCardArgument<
+                PluginStorePlane,
+                ControlPlanes,
+                Methods,
+                DependentControlPlanes,
+                DependentMethods
+            >;
+        }
+        : {}) &
+    ('index' extends ControlPlanes
+        ? {
+            index: AddImplicitLearnCardArgument<
+                PluginIndexPlane,
+                ControlPlanes,
+                Methods,
+                DependentControlPlanes,
+                DependentMethods
+            >;
+        }
+        : {}) &
+    ('cache' extends ControlPlanes
+        ? {
+            cache: AddImplicitLearnCardArgument<
+                PluginCachePlane,
+                ControlPlanes,
+                Methods,
+                DependentControlPlanes,
+                DependentMethods
+            >;
+        }
+        : {}) &
+    ('id' extends ControlPlanes
+        ? {
+            id: AddImplicitLearnCardArgument<
+                PluginIdPlane,
+                ControlPlanes,
+                Methods,
+                DependentControlPlanes,
+                DependentMethods
+            >;
+        }
+        : {}) &
+    ('context' extends ControlPlanes
+        ? {
+            context: AddImplicitLearnCardArgument<
+                PluginContextPlane,
+                ControlPlanes,
+                Methods,
+                DependentControlPlanes,
+                DependentMethods
+            >;
+        }
+        : {}));
+
+/** @group Universal Wallets */
+export type LearnCard<
+    Plugins extends Plugin[] = [],
+    ControlPlanes extends ControlPlane = GetPlanesForPlugins<Plugins>,
+    PluginMethods = GetPluginMethods<Plugins>
+> = {
+    plugins: Plugins;
+    invoke: PluginMethods;
+    addPlugin: <NewPlugin extends Plugin>(
+        plugin: NewPlugin
+    ) => Promise<LearnCard<[...Plugins, NewPlugin]>>;
+    debug?: typeof console.log;
+} & (IsAnyOrNever<ControlPlanes> extends true
+    ? {}
+    : ('read' extends ControlPlanes ? { read: LearnCardReadPlane<Plugins> } : {}) &
+    ('store' extends ControlPlanes ? { store: LearnCardStorePlane<Plugins> } : {}) &
+    ('index' extends ControlPlanes ? { index: LearnCardIndexPlane<Plugins> } : {}) &
+    ('cache' extends ControlPlanes ? { cache: LearnCardCachePlane<Plugins> } : {}) &
+    ('id' extends ControlPlanes ? { id: LearnCardIdPlane<Plugins> } : {}) &
+    ('context' extends ControlPlanes ? { context: LearnCardContextPlane<Plugins> } : {}));

package/src/wallet/base/crypto.ts

@@ -0,0 +1,5 @@
+import crypto from 'isomorphic-webcrypto';
+
+if (typeof window === 'undefined' && !globalThis.crypto) globalThis.crypto = crypto;
+
+export default crypto;

package/src/wallet/base/helpers.ts

@@ -0,0 +1,73 @@
+import { LearnCard, Plugin } from '../../types/wallet';
+import { ControlPlane } from '../../types/planes';
+
+/** Type guard for removing null/undefined */
+export const isNotNull = <T>(item?: T | null): item is T => !!item;
+
+/** Removes null/undefined from items in an array */
+export const filterNulls = <T>(array: (T | null | undefined)[]) => array.filter(isNotNull);
+
+/**
+ * Loops through an array, running a callback over it until that callback returns a value. Once the
+ * first value is found, it is returned. If no value is found, undefined is returned instead
+ */
+export const findFirstResult = <T, U>(
+    array: T[],
+    callback: (item: T) => U | undefined
+): U | undefined => {
+    return array.reduce<U | undefined>((result, item) => {
+        if (result !== undefined) return result;
+
+        return callback(item);
+    }, undefined);
+};
+
+export const pluginImplementsPlane = <Plane extends ControlPlane>(
+    plugin: Plugin,
+    plane: Plane
+): plugin is Plugin<any, Plane> => {
+    if (plane === 'read') return 'get' in (plugin.read ?? {});
+    if (plane === 'store') return 'upload' in (plugin.store ?? {});
+    if (plane === 'index') return 'get' in (plugin.index ?? {});
+    if (plane === 'cache') return 'getIndex' in (plugin.cache ?? {});
+    if (plane === 'id') return 'did' in (plugin.id ?? {});
+    if (plane === 'context') return 'resolveStaticDocument' in (plugin.context ?? {});
+
+    return false;
+};
+
+export const learnCardImplementsPlane = <Plane extends ControlPlane>(
+    learnCard: LearnCard<any, any, any>,
+    plane: Plane
+): learnCard is LearnCard<any, Plane> => {
+    if (plane === 'read') return 'read' in learnCard;
+    if (plane === 'store') return 'store' in learnCard;
+    if (plane === 'index') return 'index' in learnCard;
+    if (plane === 'cache') return 'cache' in learnCard;
+    if (plane === 'id') return 'id' in learnCard;
+    if (plane === 'context') return 'context' in learnCard;
+
+    return false;
+};
+
+export const mapObject = <T extends string, U, V>(
+    obj: Record<T, U>,
+    callback: (value: U, index: number) => V
+): Record<T, V> => {
+    return Object.fromEntries(
+        Object.entries<U>(obj).map(([key, value], index) => [key, callback(value, index)])
+    ) as any;
+};
+
+export const isFulfilledAndNotEmpty = <T>(
+    input: PromiseSettledResult<T>
+): input is PromiseFulfilledResult<T> => input.status === 'fulfilled' && !!input.value;
+
+export const uniqBy = <Obj extends Record<string, any>>(
+    array: Obj[],
+    key: keyof Obj | ((obj: Obj) => any)
+) => {
+    return [
+        ...new Map(array.map(obj => [key instanceof Function ? key(obj) : obj[key], obj])).values(),
+    ];
+};

package/src/wallet/base/index.ts

@@ -0,0 +1,2 @@
+export * from './wallet';
+export * from './crypto';