@timeback/clr 0.1.0

package/dist/factory.d.ts

@@ -0,0 +1,38 @@
+/**
+ * CLR Client Factory
+ *
+ * Creates ClrClient classes bound to specific provider registries.
+ */
+import { CredentialsResource, DiscoveryResource } from './resources';
+import type { AuthCheckResult, ProviderRegistry, TimebackProvider } from '@timeback/internal-client-infra';
+import type { ClrClientConfig, ClrTransportLike } from './types';
+/**
+ * Create a ClrClient class bound to a specific provider registry.
+ *
+ * @param registry - Provider registry to use (defaults to all Timeback platforms)
+ * @returns ClrClient class bound to the registry
+ */
+export declare function createClrClient(registry?: ProviderRegistry): {
+    new (config?: ClrClientConfig): {
+        /** @internal */
+        readonly transport: ClrTransportLike;
+        /** @internal */
+        readonly _provider?: TimebackProvider | undefined;
+        /** Upsert and manage CLR verifiable credentials */
+        readonly credentials: CredentialsResource;
+        /** Discover CLR API capabilities and endpoints */
+        readonly discovery: DiscoveryResource;
+        /**
+         * Get the underlying transport for advanced use cases.
+         * @returns The transport instance used by this client
+         */
+        getTransport(): ClrTransportLike;
+        /**
+         * Verify that OAuth authentication is working.
+         * @returns Auth check result
+         * @throws {Error} If client was initialized with custom transport (no provider)
+         */
+        checkAuth(): Promise<AuthCheckResult>;
+    };
+};
+//# sourceMappingURL=factory.d.ts.map

package/dist/factory.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"factory.d.ts","sourceRoot":"","sources":["../src/factory.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAMH,OAAO,EAAE,mBAAmB,EAAE,iBAAiB,EAAE,MAAM,aAAa,CAAA;AAGpE,OAAO,KAAK,EAAE,eAAe,EAAE,gBAAgB,EAAE,gBAAgB,EAAE,MAAM,iCAAiC,CAAA;AAC1G,OAAO,KAAK,EAAE,eAAe,EAAE,gBAAgB,EAAE,MAAM,SAAS,CAAA;AAEhE;;;;;GAKG;AACH,wBAAgB,eAAe,CAAC,QAAQ,GAAE,gBAA4C;;QAOpF,gBAAgB;;QAGhB,gBAAgB;;QAGhB,mDAAmD;;QAEnD,kDAAkD;;QA0ClD;;;WAGG;;QAKH;;;;WAIG;;;EASJ"}

package/dist/index.d.ts

@@ -0,0 +1,589 @@
+import * as _timeback_internal_client_infra from '@timeback/internal-client-infra';
+import { ClientConfig, TransportOnlyConfig, ClrPaths, RequestOptions, ProviderClientConfig, TransportConfigWithTokenProvider, ProviderRegistry, TimebackProvider, AuthCheckResult, BaseTransport } from '@timeback/internal-client-infra';
+export { AuthCheckResult, EnvAuth, Environment, ExplicitAuth } from '@timeback/internal-client-infra';
+
+/**
+ * CLR Credential Types
+ *
+ * Types for the Comprehensive Learner Record (CLR) v2.0 Verifiable Credential model.
+ * Based on the IMS Global CLR v2.0 specification.
+ */
+
+// ═══════════════════════════════════════════════════════════════════════════════
+// ENUMS
+// ═══════════════════════════════════════════════════════════════════════════════
+
+/**
+ * Types of achievements that can be represented in a CLR credential.
+ *
+ * Defined by the IMS Global CLR v2.0 specification.
+ * Custom extensions are supported via the `ext:` prefix.
+ */
+type AchievementType =
+	| 'Achievement'
+	| 'ApprenticeshipCertificate'
+	| 'Assessment'
+	| 'Assignment'
+	| 'AssociateDegree'
+	| 'Award'
+	| 'Badge'
+	| 'BachelorDegree'
+	| 'Certificate'
+	| 'CertificateOfCompletion'
+	| 'Certification'
+	| 'CommunityService'
+	| 'Competency'
+	| 'Course'
+	| 'CoCurricular'
+	| 'Degree'
+	| 'Diploma'
+	| 'DoctoralDegree'
+	| 'Fieldwork'
+	| 'GeneralEducationDevelopment'
+	| 'JourneymanCertificate'
+	| 'LearningProgram'
+	| 'License'
+	| 'Membership'
+	| 'ProfessionalDoctorate'
+	| 'QualityAssuranceCredential'
+	| 'MasterCertificate'
+	| 'MasterDegree'
+	| 'MicroCredential'
+	| 'ResearchDoctorate'
+	| 'SecondarySchoolDiploma'
+	| (string & {})
+
+/**
+ * Types of associations between achievements or credentials.
+ */
+type AssociationType =
+	| 'exactMatchOf'
+	| 'isChildOf'
+	| 'isParentOf'
+	| 'isPartOf'
+	| 'isPeerOf'
+	| 'isRelatedTo'
+	| 'precedes'
+	| 'replacedBy'
+
+// ═══════════════════════════════════════════════════════════════════════════════
+// SHARED TYPES
+// ═══════════════════════════════════════════════════════════════════════════════
+
+/**
+ * Image reference following the IMS Global Image model.
+ */
+interface ClrImage {
+	/** The URI or Data URI of the image. */
+	id: string
+	/** MUST be the IRI 'Image'. */
+	type: 'Image'
+	/** The caption for the image. */
+	caption?: string
+}
+
+/**
+ * Profile representing an issuer or creator of a credential.
+ *
+ * Used for both the top-level issuer and achievement creators.
+ */
+interface ClrProfile {
+	/** URI identifier for the profile. */
+	id: string
+	/** Type identifiers (e.g., ['Profile']). */
+	type: string[]
+	/** Display name of the profile. */
+	name?: string
+	/** URL of the profile's website. */
+	url?: string
+	/** Phone number for the profile. */
+	phone?: string
+	/** Description of the profile. */
+	description?: string
+	/** Image associated with the profile. */
+	image?: ClrImage
+	/** Email address for the profile. */
+	email?: string
+}
+
+/**
+ * Cryptographic proof ensuring credential integrity and authenticity.
+ *
+ * Supports DataIntegrityProof, JsonWebSignature2020, and other proof types.
+ */
+interface ClrProof {
+	/** The proof type (e.g., 'DataIntegrityProof', 'JsonWebSignature2020'). */
+	type: string
+	/** The purpose of the proof (e.g., 'assertionMethod'). */
+	proofPurpose: string
+	/** URI of the verification method used to create the proof. */
+	verificationMethod: string
+	/** ISO 8601 datetime when the proof was created. */
+	created: string
+	/** The proof value (e.g., base64-encoded signature). */
+	proofValue: string
+	/** The cryptographic suite used (e.g., 'eddsa-rdfc-2022'). */
+	cryptosuite?: string
+}
+
+/**
+ * Schema reference for validating credentials.
+ */
+interface ClrCredentialSchema {
+	/** URI of the credential schema. */
+	id: string
+	/** Schema validator type. */
+	type: '1EdTechJsonSchemaValidator2019'
+}
+
+// ═══════════════════════════════════════════════════════════════════════════════
+// ACHIEVEMENT TYPES
+// ═══════════════════════════════════════════════════════════════════════════════
+
+/**
+ * Criteria for earning an achievement.
+ */
+interface AchievementCriteria {
+	/** The URI of a webpage that describes the criteria. */
+	id?: string
+	/** A narrative of what is needed to earn the achievement. */
+	narrative?: string
+}
+
+/**
+ * An achievement that a learner has earned.
+ *
+ * Represents a competency, course completion, badge, or other accomplishment.
+ */
+interface Achievement {
+	/** URI identifier for the achievement. */
+	id: string
+	/** Type identifiers (e.g., ['Achievement']). */
+	type: string[]
+	/** Display name of the achievement. */
+	name: string
+	/** Description of the achievement. */
+	description: string
+	/** Criteria for earning the achievement. */
+	criteria: AchievementCriteria
+	/** Image associated with the achievement. */
+	image?: ClrImage
+	/** Classification of the achievement. */
+	achievementType?: AchievementType
+	/** The profile of the entity that created the achievement. */
+	creator?: ClrProfile
+}
+
+// ═══════════════════════════════════════════════════════════════════════════════
+// IDENTITY TYPES
+// ═══════════════════════════════════════════════════════════════════════════════
+
+/**
+ * Identity object for the credential subject.
+ *
+ * Used to identify the learner, optionally with hashed identity for privacy.
+ */
+interface IdentityObject {
+	/** MUST be 'IdentityObject'. */
+	type: 'IdentityObject'
+	/** The identity hash (or plain value if not hashed). */
+	identityHash: string
+	/** The type of identity (e.g., 'emailAddress', 'sourcedId'). */
+	identityType: string
+	/** Whether the identityHash is hashed. */
+	hashed: boolean
+	/** Salt used for hashing, if applicable. */
+	salt?: string
+}
+
+// ═══════════════════════════════════════════════════════════════════════════════
+// ASSOCIATION TYPES
+// ═══════════════════════════════════════════════════════════════════════════════
+
+/**
+ * Association between two achievements or credentials.
+ */
+interface Association {
+	/** MUST be 'Association'. */
+	type: 'Association'
+	/** The type of association. */
+	associationType: AssociationType
+	/** URI of the source entity. */
+	sourceId: string
+	/** URI of the target entity. */
+	targetId: string
+}
+
+// ═══════════════════════════════════════════════════════════════════════════════
+// VERIFIABLE CREDENTIAL (NESTED)
+// ═══════════════════════════════════════════════════════════════════════════════
+
+/**
+ * Credential subject for a nested verifiable credential.
+ */
+interface NestedCredentialSubject {
+	/** URI identifier for the subject. */
+	id?: string
+}
+
+/**
+ * A verifiable credential nested within a CLR.
+ *
+ * Represents individual assertions (e.g., AchievementCredentials,
+ * OpenBadgeCredentials) packaged inside the CLR.
+ */
+interface VerifiableCredential {
+	/** JSON-LD context URIs. */
+	'@context': string[]
+	/** URI identifier for the credential. */
+	id: string
+	/** Type identifiers (e.g., ['VerifiableCredential', 'AchievementCredential']). */
+	type: string[]
+	/** The issuer of this credential. */
+	issuer: ClrProfile
+	/** ISO 8601 datetime from which the credential is valid. */
+	validFrom: string
+	/** ISO 8601 datetime until which the credential is valid. */
+	validUntil?: string
+	/** The subject of the credential. */
+	credentialSubject: NestedCredentialSubject
+	/** Cryptographic proofs for this credential. */
+	proof?: ClrProof[]
+}
+
+// ═══════════════════════════════════════════════════════════════════════════════
+// CREDENTIAL SUBJECT
+// ═══════════════════════════════════════════════════════════════════════════════
+
+/**
+ * The subject of a CLR credential.
+ *
+ * Contains the learner's identity, achievements, nested credentials,
+ * and associations between them.
+ */
+interface ClrCredentialSubject {
+	/** URI identifier for the credential subject (the learner). */
+	id?: string
+	/** Type identifiers (e.g., ['ClrSubject']). */
+	type: string[]
+	/** Identity objects for the learner. */
+	identifier?: IdentityObject[]
+	/** Achievements earned by the learner. */
+	achievement?: Achievement[]
+	/** Individual verifiable credentials packaged in the CLR. */
+	verifiableCredential: VerifiableCredential[]
+	/** Associations between achievements or credentials. */
+	association?: Association[]
+}
+
+// ═══════════════════════════════════════════════════════════════════════════════
+// CLR CREDENTIAL
+// ═══════════════════════════════════════════════════════════════════════════════
+
+/**
+ * A Comprehensive Learner Record (CLR) v2.0 Verifiable Credential.
+ *
+ * The top-level data structure representing a learner's full set of
+ * achievements issued by one or more learning providers. The platform
+ * acts as the publisher, digitally signing the CLR to ensure authenticity.
+ *
+ * Required fields for upsert: `@context`, `id`, `type`, `issuer`, `name`,
+ * `validFrom`, `credentialSubject`.
+ */
+interface ClrCredential {
+	/** JSON-LD context URIs. */
+	'@context': string[]
+	/** URI identifier for the CLR credential. */
+	id: string
+	/** Type identifiers (e.g., ['VerifiableCredential', 'ClrCredential']). */
+	type: string[]
+	/** The issuer (publisher) of the CLR. */
+	issuer: ClrProfile
+	/** Display name of the CLR. */
+	name: string
+	/** Description of the CLR. */
+	description?: string
+	/** ISO 8601 datetime from which the CLR is valid. */
+	validFrom: string
+	/** ISO 8601 datetime until which the CLR is valid. */
+	validUntil?: string
+	/** The learner and their achievements/credentials. */
+	credentialSubject: ClrCredentialSubject
+	/** Cryptographic proofs added by the platform. */
+	proof?: ClrProof[]
+	/** Schema references for credential validation. */
+	credentialSchema?: ClrCredentialSchema[]
+}
+
+/**
+ * CLR Discovery Types
+ *
+ * Types for the CLR v2.0 API discovery endpoint.
+ */
+
+/**
+ * Response from the CLR discovery endpoint.
+ *
+ * Returns the OpenAPI 3.0 specification for the CLR v2.0 API,
+ * including available endpoints, OAuth2 flows, and supported scopes.
+ * This is a public endpoint (no auth required).
+ */
+type DiscoveryResponse = Record<string, unknown>
+
+/**
+ * Transport interface for CLR client.
+ *
+ * Extends base transport requirements with CLR-specific paths.
+ * Required when using transport mode with ClrClient.
+ */
+interface ClrTransportLike {
+    /** Base URL of the API */
+    baseUrl: string;
+    /** API path profiles for CLR operations */
+    paths: ClrPaths;
+    /** Make an authenticated request */
+    request<T>(path: string, options?: RequestOptions): Promise<T>;
+}
+/**
+ * All supported CLR client configuration types.
+ *
+ * Supports four modes:
+ * - **Provider mode**: `{ provider: TimebackProvider }` — pre-built provider with token sharing
+ * - **Environment mode**: `{ platform?, env, auth }` — Timeback hosted APIs
+ * - **Explicit mode**: `{ baseUrl, auth: { authUrl } }` — custom API URLs
+ * - **Transport mode**: `{ transport }` — custom transport with paths
+ */
+type ClrClientConfig = ClientConfig | TransportOnlyConfig<ClrTransportLike> | ProviderClientConfig;
+/**
+ * Configuration for CLR transport.
+ */
+interface ClrTransportConfig extends TransportConfigWithTokenProvider {
+    /** API path profiles for CLR operations */
+    paths: ClrPaths;
+}
+/**
+ * Instance type of ClrClient.
+ */
+type ClrClientInstance = InstanceType<typeof ClrClient>;
+
+/**
+ * Credentials Resource
+ *
+ * Manage CLR (Comprehensive Learner Record) credentials.
+ */
+
+/**
+ * Credentials resource for CLR credential management.
+ *
+ * Provides the ability to upsert verifiable CLR credentials.
+ * The platform acts as the publisher, digitally signing credentials
+ * to ensure their authenticity and integrity.
+ */
+declare class CredentialsResource {
+    private readonly transport;
+    constructor(transport: ClrTransportLike);
+    /**
+     * Upsert a Comprehensive Learner Record (CLR) credential.
+     *
+     * Creates a new credential or updates an existing one based on the credential ID.
+     * The platform will digitally sign the credential, adding a cryptographic proof
+     * to ensure authenticity.
+     *
+     * @param credential - The CLR credential to upsert
+     * @returns The upserted credential with platform-added proof
+     *
+     * @example
+     * ```typescript
+     * const result = await client.credentials.upsert({
+     *   '@context': [
+     *     'https://www.w3.org/ns/credentials/v2',
+     *     'https://purl.imsglobal.org/spec/clr/v2p0/context-2.0.1',
+     *   ],
+     *   id: 'urn:uuid:example-clr-id',
+     *   type: ['VerifiableCredential', 'ClrCredential'],
+     *   issuer: {
+     *     id: 'https://example.edu',
+     *     type: ['Profile'],
+     *     name: 'Example University',
+     *   },
+     *   name: 'Student Transcript',
+     *   validFrom: '2024-01-01T00:00:00Z',
+     *   credentialSubject: {
+     *     type: ['ClrSubject'],
+     *     verifiableCredential: [
+     *       // nested credentials...
+     *     ],
+     *   },
+     * })
+     * ```
+     */
+    upsert(credential: ClrCredential): Promise<ClrCredential>;
+}
+
+/**
+ * Discovery Resource
+ *
+ * CLR v2.0 API discovery endpoint.
+ */
+
+/**
+ * Discovery resource for CLR API capabilities.
+ *
+ * Provides access to the CLR v2.0 API discovery endpoint,
+ * which returns the OpenAPI specification including available
+ * endpoints, OAuth2 flows, and supported scopes.
+ *
+ * NOTE: The CLR v2.0 spec declares this endpoint as public (`security: []`),
+ * but the BeyondAI implementation enforces OAuth authentication. This client
+ * sends credentials on all requests, so this is handled transparently.
+ */
+declare class DiscoveryResource {
+    private readonly transport;
+    constructor(transport: ClrTransportLike);
+    /**
+     * Get CLR v2.0 API discovery information.
+     *
+     * Returns the OpenAPI 3.0 specification for the CLR v2.0 API,
+     * allowing clients to dynamically discover the service's capabilities.
+     *
+     * NOTE: Despite the spec declaring this as a public endpoint, the
+     * BeyondAI API requires authentication. An authenticated transport
+     * is required.
+     *
+     * @returns Discovery information (OpenAPI spec object)
+     *
+     * @example
+     * ```typescript
+     * const discovery = await client.discovery.get()
+     * console.log(discovery) // OpenAPI 3.0 spec
+     * ```
+     */
+    get(): Promise<DiscoveryResponse>;
+}
+
+/**
+ * CLR Client
+ *
+ * Main entry point for the CLR SDK.
+ */
+/**
+ * CLR API client for Comprehensive Learner Record management.
+ *
+ * Provides access to CLR endpoints including credential upsert
+ * and API discovery.
+ *
+ * @example
+ * ```typescript
+ * // Environment mode (Timeback APIs)
+ * const client = new ClrClient({
+ *   env: 'staging', // or 'production'
+ *   auth: {
+ *     clientId: 'your-client-id',
+ *     clientSecret: 'your-client-secret',
+ *   },
+ * })
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // Provider mode (shared tokens)
+ * import { TimebackProvider } from '@timeback/internal-client-infra'
+ *
+ * const provider = new TimebackProvider({
+ *   platform: 'BEYOND_AI',
+ *   env: 'staging',
+ *   auth: { clientId: '...', clientSecret: '...' },
+ * })
+ *
+ * const client = new ClrClient({ provider })
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // Explicit mode (custom API)
+ * const client = new ClrClient({
+ *   baseUrl: 'https://api.example.com',
+ *   auth: {
+ *     clientId: 'your-client-id',
+ *     clientSecret: 'your-client-secret',
+ *     authUrl: 'https://auth.example.com/oauth2/token',
+ *   },
+ * })
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // Environment variables fallback
+ * // Set CLR_BASE_URL, CLR_TOKEN_URL,
+ * // CLR_CLIENT_ID, CLR_CLIENT_SECRET
+ * const client = new ClrClient()
+ * ```
+ */
+declare const ClrClient: {
+    new (config?: ClrClientConfig): {
+        readonly transport: ClrTransportLike;
+        readonly _provider?: _timeback_internal_client_infra.TimebackProvider | undefined;
+        readonly credentials: CredentialsResource;
+        readonly discovery: DiscoveryResource;
+        getTransport(): ClrTransportLike;
+        checkAuth(): Promise<_timeback_internal_client_infra.AuthCheckResult>;
+    };
+};
+
+/**
+ * CLR Client Factory
+ *
+ * Creates ClrClient classes bound to specific provider registries.
+ */
+
+/**
+ * Create a ClrClient class bound to a specific provider registry.
+ *
+ * @param registry - Provider registry to use (defaults to all Timeback platforms)
+ * @returns ClrClient class bound to the registry
+ */
+declare function createClrClient(registry?: ProviderRegistry): {
+    new (config?: ClrClientConfig): {
+        /** @internal */
+        readonly transport: ClrTransportLike;
+        /** @internal */
+        readonly _provider?: TimebackProvider | undefined;
+        /** Upsert and manage CLR verifiable credentials */
+        readonly credentials: CredentialsResource;
+        /** Discover CLR API capabilities and endpoints */
+        readonly discovery: DiscoveryResource;
+        /**
+         * Get the underlying transport for advanced use cases.
+         * @returns The transport instance used by this client
+         */
+        getTransport(): ClrTransportLike;
+        /**
+         * Verify that OAuth authentication is working.
+         * @returns Auth check result
+         * @throws {Error} If client was initialized with custom transport (no provider)
+         */
+        checkAuth(): Promise<AuthCheckResult>;
+    };
+};
+
+/**
+ * Transport Layer
+ *
+ * HTTP transport for CLR API communication.
+ */
+
+/**
+ * HTTP transport layer for CLR API communication.
+ *
+ * CLR uses the IMS Global error format, which is handled by the
+ * base transport's built-in IMS error parsing. No custom pagination
+ * is needed since CLR endpoints don't return paginated results.
+ */
+declare class Transport extends BaseTransport {
+    /** API path profiles for CLR operations */
+    readonly paths: ClrPaths;
+    constructor(config: ClrTransportConfig);
+}
+
+export { ClrClient, Transport, createClrClient };
+export type { Achievement, AchievementCriteria, AchievementType, Association, AssociationType, ClrClientConfig, ClrClientInstance, ClrCredential, ClrCredentialSchema, ClrCredentialSubject, ClrImage, ClrProfile, ClrProof, DiscoveryResponse, IdentityObject, NestedCredentialSubject, VerifiableCredential };

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAmCG;AAMH,OAAO,EAAE,SAAS,EAAE,KAAK,iBAAiB,EAAE,MAAM,UAAU,CAAA;AAC5D,OAAO,EAAE,eAAe,EAAE,MAAM,WAAW,CAAA;AAE3C,YAAY,EAAE,eAAe,EAAE,MAAM,gBAAgB,CAAA;AAMrD,YAAY,EAAE,WAAW,EAAE,OAAO,EAAE,YAAY,EAAE,MAAM,gBAAgB,CAAA;AAExE,YAAY,EAAE,eAAe,EAAE,MAAM,iCAAiC,CAAA;AAEtE,YAAY,EACX,WAAW,EACX,mBAAmB,EACnB,eAAe,EACf,WAAW,EACX,eAAe,EACf,aAAa,EACb,mBAAmB,EACnB,oBAAoB,EACpB,QAAQ,EACR,UAAU,EACV,QAAQ,EACR,iBAAiB,EACjB,cAAc,EACd,uBAAuB,EACvB,oBAAoB,GACpB,MAAM,+BAA+B,CAAA;AAMtC,OAAO,EAAE,SAAS,EAAE,MAAM,OAAO,CAAA"}