@memberjunction/connector-totara 0.2.0

package/dist/TotaraConnector.d.ts

@@ -0,0 +1,238 @@
+import { type UserInfo } from '@memberjunction/core';
+import type { MJCompanyIntegrationEntity } from '@memberjunction/core-entities';
+import { BaseRESTIntegrationConnector, type RESTAuthContext, type RESTResponse, type PaginationState, type PaginationType, type ConnectionTestResult, type FetchContext, type FetchBatchResult, type CreateRecordContext, type UpdateRecordContext, type DeleteRecordContext, type CRUDResult, type SourceSchemaInfo } from '@memberjunction/integration-engine';
+/** Resolved connection settings (secret token + per-tenant base URL). NO tenant constants in code. */
+interface TotaraConfig {
+    /** The per-user Web Service token (wstoken) — injected as a request PARAM, never a header. */
+    Token: string;
+    /** The tenant's site base URL (e.g. https://learn.example.org). */
+    BaseURL: string;
+}
+/** Auth context threaded through every request. Carries the token + the resolved RPC endpoint. */
+export interface TotaraAuthContext extends RESTAuthContext {
+    /** wstoken — injected as a urlencoded body param by MakeHTTPRequest. */
+    Token: string;
+    /** Fully-resolved RPC endpoint: `{base_url}/webservice/rest/server.php`. */
+    Endpoint: string;
+}
+/**
+ * The structured RPC request handed to {@link TotaraConnector.MakeHTTPRequest} as its `body`.
+ * MakeHTTPRequest is where the urlencoded form (wstoken + moodlewsrestformat + wsfunction + params) is
+ * actually built — so a test that mocks MakeHTTPRequest captures the meaningful wire intent (function +
+ * params). `Params` keys are already Moodle-shaped (flat for reads; bracket-notation for write arrays).
+ */
+export interface MoodleRPCRequest {
+    /** The wsfunction operation selector (e.g. core_course_get_courses). */
+    WsFunction: string;
+    /** Flat urlencoded params. wstoken/moodlewsrestformat/wsfunction are added by MakeHTTPRequest. */
+    Params: Record<string, string | number>;
+}
+export declare class TotaraConnector extends BaseRESTIntegrationConnector {
+    /** Resolved auth per CompanyIntegration.ID — avoids re-loading the credential every fetch/CRUD call. */
+    protected authCache: Map<string, TotaraAuthContext>;
+    /** Verbatim MJ: Integrations.Name (three-way identity invariant). */
+    get IntegrationName(): string;
+    /** Create is wired (courses/users/cohorts/groups/groupings/notes/categories + association adds). */
+    get SupportsCreate(): boolean;
+    /** Update is wired for the objects that expose an update_* wsfunction (courses/users/cohorts/…/notes). */
+    get SupportsUpdate(): boolean;
+    /** Delete is wired for the objects that expose a delete/unenrol/remove wsfunction. */
+    get SupportsDelete(): boolean;
+    /**
+     * core_webservice_get_site_info enumerates the functions ENABLED FOR THE CALLING TOKEN (role/capability
+     * gated), NOT a complete-gamut describe of the site — so keep the base default false: a
+     * comprehensive-refresh must never deactivate a Declared IO/IOF because one token can't see it.
+     */
+    get DiscoveryIsAuthoritative(): boolean;
+    /**
+     * Keyset/no-watermark resume hint — returns the IO's declared `Configuration.stableOrderingKey`
+     * (usually the record's `id`), or null when the object declares none. Read from the frozen metadata,
+     * never guessed.
+     */
+    StableOrderingKey(objectName: string): string | null;
+    /**
+     * Verifies the wstoken + endpoint. The primary probe is core_webservice_get_site_info (it also carries
+     * the site name / release), BUT some Totara instances / token-service configurations throw a NON-auth
+     * "No service found in get_site_info" codingerror on it even for a fully valid token (verified live
+     * against a real instance). So a non-auth failure on site-info FALLS BACK to a lightweight real read
+     * (core_course_get_categories): if that returns a record array, the token is valid and the connection
+     * works. Only a genuine auth error (invalid/expired token, access denied) — or a failing fallback read —
+     * reports failure.
+     */
+    TestConnection(companyIntegration: MJCompanyIntegrationEntity, contextUser: UserInfo): Promise<ConnectionTestResult>;
+    /** A genuine credential / authorization failure — terminal; never fall back on these. */
+    private isTotaraAuthError;
+    /**
+     * Fallback connection check: a valid wstoken that returns a record array from a lightweight read
+     * (core_course_get_categories) proves the connection even when site-info is unavailable on the instance.
+     */
+    private verifyConnectionViaRead;
+    /** Resolves the wstoken + endpoint from the credential store / Configuration. Cached per connection. */
+    protected Authenticate(companyIntegration: MJCompanyIntegrationEntity, contextUser: UserInfo): Promise<TotaraAuthContext>;
+    /**
+     * Content-type headers for a Moodle REST-RPC POST. The wstoken is NOT a header — it is injected as a
+     * urlencoded body PARAM in {@link MakeHTTPRequest} from the auth context.
+     */
+    protected BuildHeaders(_auth: RESTAuthContext): Record<string, string>;
+    /** The fully-resolved RPC endpoint (`{base_url}/webservice/rest/server.php`) from the auth context. */
+    protected GetBaseURL(_companyIntegration: MJCompanyIntegrationEntity, auth: RESTAuthContext): string;
+    /**
+     * The Moodle REST-RPC transport boundary. `body` MUST be a {@link MoodleRPCRequest}; this builds the
+     * urlencoded form — `wstoken` (from the auth context) + `moodlewsrestformat=json` + `wsfunction=<fn>` +
+     * every entry of `Params` (already Moodle-shaped) — POSTs it, and parses the JSON response. Test
+     * subclasses override this to capture the request and return canned bodies.
+     */
+    protected MakeHTTPRequest(auth: RESTAuthContext, url: string, method: string, headers: Record<string, string>, body?: unknown): Promise<RESTResponse>;
+    /**
+     * Extracts the record array from a Moodle response, DETECTING the exception envelope first: Moodle
+     * signals errors via a 200-status body `{exception, errorcode, message, debuginfo}` — this throws an
+     * ERROR carrying the errorcode rather than returning a silent empty (frozen contract ErrorResponseShape).
+     * `responseDataKey` is the wrapping envelope key (e.g. `users`, `items`, `sitenotes`); null → the body is
+     * a bare top-level array. A single wrapped object is returned as a one-element array.
+     */
+    protected NormalizeResponse(rawBody: unknown, responseDataKey: string | null): Record<string, unknown>[];
+    /**
+     * Moodle list functions carry no envelope-level `HasMore`; termination is inferred from a full page
+     * (record count == page size). Hierarchy `*_index` functions DO return `{page, pages, total}` metadata —
+     * when present that is used for an exact stop. `None` never paginates.
+     */
+    protected ExtractPaginationInfo(rawBody: unknown, paginationType: PaginationType, currentPage: number, currentOffset: number, pageSize: number): PaginationState;
+    /**
+     * Never-shrink SAMPLE-UNION: enrich each object's DECLARED (docs) field set with fields observed by live
+     * SAMPLING ({@link DiscoverFieldsViaFetch}) so a tenant's custom user/course fields reach the schema
+     * without ever losing or narrowing a declared field. Per object, parallel + best-effort — a sampling
+     * failure (e.g. a scope-requiring function) leaves that object's declared fields authoritative. Wire at
+     * IntrospectSchema, NEVER DiscoverFields (DiscoverFieldsViaFetch falls back to DiscoverFields → recursion).
+     */
+    IntrospectSchema(companyIntegration: MJCompanyIntegrationEntity, contextUser: UserInfo): Promise<SourceSchemaInfo>;
+    /**
+     * Reads one object via its `Configuration.wsfunction`. Applies Offset (`limitfrom`/`limitnum(ber)`) or
+     * PageNumber (`page`/`perpage`) pagination from the object's declared `paginationParams`, merges any
+     * declared scope args, and unions every record collection the envelope exposes (single `responseEnvelopeKey`
+     * OR multi-collection `recordCollectionKeys` — e.g. Notes' sitenotes+coursenotes+personalnotes). Fetches
+     * ONE page per call; the engine loops on HasMore. Full-record pass-through: every source key reaches Fields.
+     */
+    FetchChanges(ctx: FetchContext): Promise<FetchBatchResult>;
+    /**
+     * Parent-scoped RPC fetch. Some Moodle read functions REQUIRE a parent id param — e.g.
+     * core_enrol_get_enrolled_users / core_course_get_contents / core_enrol_get_course_enrolment_methods all
+     * need a `courseid`. Declared via `Configuration.parentScope = { parentWsFunction, paramName, parentIdField? }`.
+     * The connector loads the parent ids from the parent's own list wsfunction, then fires ONE request per
+     * parent — keyset-resumable over the parent ids (ctx.AfterKeyValue), bounded per call (engine loops until
+     * HasMore=false), concurrency + rate-limit governed by the engine hooks. A per-parent failure (e.g. an
+     * accessexception on one course) is surfaced as a warning, never fatal to the whole batch.
+     */
+    private fetchParentScoped;
+    /** Bounded-concurrency runner (the base's RunBounded is private). Single-threaded async → array pushes are safe. */
+    private runParentBounded;
+    /**
+     * Create via the object's `Configuration.writeFunctions.create` wsfunction, encoding the record as a
+     * Moodle bracket-notation array (`<param>[0][field]=...`). The new id is read from the response per
+     * `createResponseIDField`; association creates (no server id) synthesize a deterministic identity from the
+     * sent attributes. EITHER way the result routes through {@link BuildCreatedResult} so an empty id fails
+     * LOUDLY — never a hand-built `{Success:true, ExternalID:''}`.
+     */
+    CreateRecord(ctx: CreateRecordContext): Promise<CRUDResult>;
+    /**
+     * Update via `Configuration.writeFunctions.update`, injecting the target ExternalID under the object's PK
+     * field name inside the bracket-notation array body.
+     */
+    UpdateRecord(ctx: UpdateRecordContext): Promise<CRUDResult>;
+    /**
+     * Delete via `Configuration.writeFunctions.delete` (verb NOT assumed — some are unenrol/remove), sending
+     * the target ExternalID in the Moodle ids array (`<param>ids[0]=<id>`).
+     */
+    DeleteRecord(ctx: DeleteRecordContext): Promise<CRUDResult>;
+    /** Shared write POST: authenticate + dispatch the wsfunction with the given (already-bracketed) params. */
+    private postWrite;
+    /** Builds the read request params: declared scope args + pagination (Offset limitfrom / PageNumber page). */
+    private buildReadParams;
+    /**
+     * Merges declared scope args for functions that require a parent scope (e.g. a courseid / userid /
+     * groupids). Two sources, both metadata-driven (never guessed): the IO's own `Configuration.defaultArgs`,
+     * and a per-connection `Configuration.objectArgs["<ObjectName>"]` override. Absent → nothing added; a
+     * scope-requiring function then returns a Moodle exception, surfaced (not swallowed) by NormalizeResponse.
+     */
+    private applyScopeArgs;
+    /**
+     * Offset pagination. `paginationParams` = [fromName, countName]. A dotted name (`options.limitfrom`) is a
+     * Moodle options-array param → emitted as `options[i][name]=limitfrom&options[i][value]=<n>`; a flat name
+     * is emitted directly. `countName` may carry alternates (`limitnum|limitnumber`) — the first is used.
+     */
+    private applyOffsetPagination;
+    /** PageNumber pagination. `paginationParams` = [pageName, sizeName?]; sizeName is optional (`page` alone). */
+    private applyPageNumberPagination;
+    /**
+     * The Moodle array-parameter name for a write body. Resolution (metadata-driven, never a baked catalog):
+     * (1) an explicit `Configuration.writeFunctions.arrayParam`; (2) the bracket prefix of a declared
+     * `updateIDField`/`deleteIDField` (e.g. `courses[0][id]` → `courses`); (3) the trailing plural token of
+     * the write function name (`core_user_create_users` → `users`). Genuinely-idiosyncratic association params
+     * (enrolments, members) should carry an explicit `arrayParam` override — see CODE_REPORT.md.
+     */
+    private resolveWriteArrayParam;
+    /** The Moodle ids-array parameter for a delete/unenrol/remove call (e.g. `courseids`). */
+    private resolveDeleteIdsParam;
+    /** Trailing plural token of a Moodle wsfunction name (`core_user_create_users` → `users`). */
+    private deriveArrayParamFromFunction;
+    /** The `[0][id]` prefix of a bracketed id-field path (`courses[0][id]` → `courses`; `courseids[0]` → `courseids`). */
+    private bracketPrefix;
+    /** The field name the ExternalID goes under on update (from a declared `updateIDField`, else the PK, else `id`). */
+    private updateIdFieldName;
+    /** Recursively renders a record into Moodle bracket-notation params under `<arrayParam>[0]`. */
+    private bracketEncodeRecord;
+    private bracketEncode;
+    /** Drops IsReadOnly source fields from a write body (respects the read-only constraint). */
+    private filterWritable;
+    /**
+     * Collection keys to extract from a read response, resolved in priority order:
+     *   1. `Configuration.recordCollectionKeys` — multi-collection union (e.g. Notes' sitenotes+coursenotes+
+     *      personalnotes), when the frozen metadata declares it.
+     *   2. The first-class `ResponseDataKey` COLUMN — the canonical "where the return wraps records" slot
+     *      (connector-code-conventions §4 / frozen-contract requirement). This is authoritative: the current
+     *      Totara metadata carries the envelope key HERE (`users`, `statuses`, `items`, …) with
+     *      `Configuration.responseEnvelopeKey` null, so the column MUST be read or a `{users:[…]}` envelope
+     *      would be mis-emitted as a single wrapper record instead of the N wrapped records.
+     *   3. `Configuration.responseEnvelopeKey` — backward-compatible fallback for older metadata shapes.
+     * A resolved `null` means the body is a bare top-level array.
+     */
+    private recordCollectionKeys;
+    private toRecordArray;
+    /**
+     * §4 identity: the declared PK when EVERY component is present + non-empty, else a deterministic content
+     * hash (so PK-less / partial-key records stay syncable + dedupable). Full-record pass-through: Fields
+     * carries the COMPLETE source record (with the synthetic id stamped into a single empty PK column).
+     */
+    private buildExternalRecord;
+    private primaryKeyFieldNames;
+    /** Pulls the created record's id from a Moodle create response (bare array of created / wrapped collection). */
+    private extractCreatedId;
+    /** Deterministic identity for an association create with no server id (matches the §4 content-hash path). */
+    private synthesizeAssociationId;
+    private detectMoodleError;
+    /** Throws when the body is a Moodle exception envelope (surfaces the errorcode) — never a silent empty. */
+    private assertNoMoodleError;
+    private buildCRUDError;
+    /** Resolves the wstoken + base_url from the credential store (secrets) + Configuration JSON (overrides). */
+    protected ParseConfig(companyIntegration: MJCompanyIntegrationEntity, contextUser: UserInfo): Promise<TotaraConfig>;
+    private loadCredentialValues;
+    private normalizeConfig;
+    /** `{base_url}/webservice/rest/server.php`, tolerant of a base_url that already includes the suffix. */
+    private buildEndpoint;
+    private parseConnectionConfig;
+    private readIOConfig;
+    private readWriteFunctions;
+    private readConfigString;
+    private readConfigStringArray;
+    private readConfigObject;
+    private parseJson;
+    private headersToObject;
+    /** The first record object in a response (bare array → [0]; wrapped → first array's [0]; object → itself). */
+    private firstRecord;
+    private firstArrayValue;
+    private recordCount;
+    private deepFindKey;
+    private asNumber;
+}
+/** Tree-shaking prevention — import and call from the package entry point. */
+export declare function LoadTotaraConnector(): void;
+export {};