@memberjunction/connector-rasa-io 2.0.0

package/dist/RasaConnector.d.ts

@@ -0,0 +1,306 @@
+import { type UserInfo } from '@memberjunction/core';
+import type { MJCompanyIntegrationEntity, MJIntegrationObjectEntity } from '@memberjunction/core-entities';
+import { BaseRESTIntegrationConnector, type ConnectionTestResult, type ExternalFieldSchema, type ExternalObjectSchema, type ExternalRecord, type FetchBatchResult, type FetchContext, type GetRecordContext, type PaginationState, type PaginationType, type RESTAuthContext, type RESTResponse, type SourceSchemaInfo } from '@memberjunction/integration-engine';
+import { z } from 'zod';
+declare const RasaConnectionConfigSchema: z.ZodObject<{
+    /** rasa.io API key presented in the token-exchange body. */
+    APIKey: z.ZodString;
+    /** Account username (email) for the token-exchange HTTP Basic header. */
+    Username: z.ZodString;
+    /** Account password for the token-exchange HTTP Basic header. */
+    Password: z.ZodString;
+    /** Optional host override (self-hosted / proxy / test double). Defaults to the vendor host root. */
+    BaseURL: z.ZodOptional<z.ZodString>;
+}, "strip", z.ZodTypeAny, {
+    APIKey: string;
+    Username: string;
+    Password: string;
+    BaseURL?: string | undefined;
+}, {
+    APIKey: string;
+    Username: string;
+    Password: string;
+    BaseURL?: string | undefined;
+}>;
+/** Connection configuration parsed from the MJ Credential (or CompanyIntegration.Configuration). */
+export type RasaConnectionConfig = z.infer<typeof RasaConnectionConfigSchema>;
+/**
+ * rasa.io connector (v1 + v2 REST, single host).
+ *
+ * Everything routine rides `BaseRESTIntegrationConnector`'s metadata-driven machinery — generic
+ * per-operation CRUD, pagination loop, template-var/parent iteration, record→ExternalRecord
+ * conversion. Four things are genuinely idiosyncratic and are the ONLY behavioural overrides:
+ *
+ *  1. **Two-step auth** — `POST /v1/tokens` (HTTP Basic + `{key}` body) mints a JWT that every
+ *     subsequent request presents in a CUSTOM `rasa-token` header, not `Authorization: Bearer`.
+ *  2. **`skip`/`limit` + response-metadata paging** — the base emits `offset`/`limit`; rasa.io uses
+ *     `skip`/`limit` (RealityProbe: "'skip' advanced past page 1 via offset") and drives the loop from
+ *     `metadata.next_link`, whose own `skip` value is numeric for offset endpoints and an opaque token
+ *     for others.
+ *  3. **`*_since` watermarks** — the incremental filter is a per-object query param
+ *     (`updated_since` / `created_since` / `archived_since`) read from the frozen contract.
+ *  4. **Conditional per-record envelope unwrapping** — rasa.io wraps each record JSON:API-style as
+ *     `{data, links}` on SOME objects. Driven strictly by the per-object `recordUnwrapPath` verdict;
+ *     never guessed (see {@link NormalizeResponse}).
+ */
+/** CANONICAL registration key — the repo's catalog convention is `ClassName` == the npm package name, so
+ *  instance discovery matches. `Integration.ClassName` is seeded to this value.
+ *  The short `RasaConnector` key below stays registered for continuity: `ConnectorFactory.Resolve` looks the
+ *  Integration row's ClassName up verbatim in the ClassFactory, so any tenant row still carrying the legacy
+ *  short name resolves rather than failing with "No connector registered". Zero cost to keep; removing it
+ *  would be a breaking change independent of this release's rename. */
+export declare class RasaConnector extends BaseRESTIntegrationConnector {
+    /** Cached JWT + mint time (idiosyncrasy #1). */
+    private cachedToken;
+    private tokenObtainedAt;
+    /** Response context for the in-flight fetch (see {@link RasaResponseContext}). */
+    private responseCtx;
+    /** Watermark value for the in-flight fetch — consumed by {@link AppendDefaultQueryParams}. */
+    private currentWatermark;
+    /** Non-fatal diagnostics raised during the in-flight fetch, drained into the FetchBatchResult. */
+    private pendingWarnings;
+    /** Running max of the watermark FIELD across the batches of one object's sync pass. */
+    private readonly watermarkHighWater;
+    /** Integration ID observed on the last operation — lets `StableOrderingKey(name)` reach the cache. */
+    private lastIntegrationID;
+    /** Merged public-spec cache (credential-free); populated lazily by discovery. */
+    private specCache;
+    /** Verbatim from the identity handoff / `MJ: Integrations.Name`. */
+    get IntegrationName(): string;
+    /** v1 `POST /persons|/posts|/lead-posts`, v2 `POST /lists|/contacts|/subscriptions` — all metadata-driven. */
+    get SupportsCreate(): boolean;
+    /** v1 `PUT /persons/{id}|/posts/{id}|/lead-posts`, v2 `PUT /contacts/{id}|/subscriptions/{id}`. */
+    get SupportsUpdate(): boolean;
+    /** v1 `DELETE /persons/{id}` (GDPR hard delete), v2 `DELETE /contacts/{id}` (archive). */
+    get SupportsDelete(): boolean;
+    /**
+     * `updated_since` / `created_since` are inclusive server-side filters over a monotonically
+     * advancing timestamp column, so the highest value seen is a safe resume point.
+     */
+    get MonotonicWatermark(): boolean;
+    /**
+     * Keyset hint the extractor emitted per object (`IntegrationObject.StableOrderingKey`). Returns the
+     * declared key, or null when the object has none — never a guess.
+     */
+    StableOrderingKey(objectName: string): string | null;
+    /**
+     * Step 1 of the vendor's documented flow: `POST {host}/v1/tokens` with an HTTP Basic
+     * `Authorization` header AND a `{ key: <apiKey> }` body; the JWT comes back at
+     * `results[0]['rasa-token']`. Step 2 (the custom header) is {@link BuildHeaders}.
+     */
+    protected Authenticate(companyIntegration: MJCompanyIntegrationEntity, contextUser: UserInfo): Promise<RESTAuthContext>;
+    /** Mints (or reuses) the session JWT. Never logs any credential-derived value. */
+    private MintToken;
+    /**
+     * Reads the JWT out of the token envelope. Primary shape is the documented
+     * `ApiResonseTokenCreated` → `results[0]['rasa-token']` (`definitions.RasaToken`); the `data`-wrapped
+     * and v2 `access_token` shapes are accepted as transport tolerance, not as a schema claim.
+     */
+    private ReadTokenFromBody;
+    /** Step 2: the JWT rides a CUSTOM header (`securityDefinitions.authorizer`), not `Authorization`. */
+    protected BuildHeaders(auth: RESTAuthContext): Record<string, string>;
+    /** Host root for every request; APIPath supplies its own `/v1` or `/v2` segment. */
+    protected GetBaseURL(_companyIntegration: MJCompanyIntegrationEntity, auth: RESTAuthContext): string;
+    private HostOf;
+    /**
+     * HTTP transport with bounded retry: network blips, a 401 (mint a fresh JWT and replay once the
+     * cached one has aged out), and 429 honouring `Retry-After` when the vendor sends one.
+     */
+    protected MakeHTTPRequest(auth: RESTAuthContext, url: string, method: string, headers: Record<string, string>, body?: unknown): Promise<RESTResponse>;
+    private BuildRequestInit;
+    /** Normalizes a fetch Response, tolerating empty/non-JSON bodies (e.g. a 204 from DELETE). */
+    private ToRESTResponse;
+    /** `Retry-After` in seconds or as an HTTP-date; null when the vendor sent neither. */
+    private RetryAfterMs;
+    private IsRetriableNetworkError;
+    private Sleep;
+    /**
+     * Strips the rasa.io response envelope. TWO layers, both metadata-driven:
+     *
+     *  1. the LIST envelope — `{ code, event, metadata, results, status_code }` — via the object's
+     *     `ResponseDataKey` (`results`, `results[].data`, `results[].lists`, …);
+     *  2. the PER-RECORD envelope — rasa.io wraps some records JSON:API-style as `{ data, links }` —
+     *     via the object's `Configuration.recordUnwrapPath`, which materializes the RealityProbe's
+     *     `recordEnvelopeShape` verdict. Present ⇒ verdict was `nested` ⇒ unwrap. **Absent ⇒ we do NOT
+     *     unwrap** — a missing verdict is DEFERRED, never resolved as "flat" by assumption. When an
+     *     un-verdicted object nonetheless arrives looking exactly like the vendor's envelope
+     *     (`{data, links}` and nothing else), we emit a `RECORD_ENVELOPE_UNVERIFIED` warning naming the
+     *     object so the gap is loud in the run artifact rather than silently mis-mapped.
+     */
+    protected NormalizeResponse(rawBody: unknown, responseDataKey: string | null): Record<string, unknown>[];
+    /**
+     * Evaluates a dotted extraction path against a response body. A segment may be a plain key or a
+     * `key[]` list segment; arrays are flattened either way, so `results`, `results[].data` and
+     * `results[].data.topics` all resolve uniformly. A null path returns the body itself (array or object).
+     */
+    private ExtractByPath;
+    /** Raises a one-per-fetch diagnostic when an un-verdicted object arrives inside the vendor envelope. */
+    private FlagUndeclaredEnvelope;
+    /**
+     * rasa.io pages with `skip` + `limit` (NOT the base's `offset`/`limit`). The `skip` value is a
+     * numeric offset on offset endpoints and an opaque token on the endpoints whose `next_link` carries
+     * a non-numeric `skip` — {@link ExtractPaginationInfo} classifies it, we replay whichever it gave us.
+     * `limit` is capped by the object's declared `DefaultPageSize` (the v1 spec's hard `maximum: 50`).
+     */
+    protected BuildPaginatedURL(basePath: string, obj: MJIntegrationObjectEntity, _page: number, offset: number, cursor?: string, effectivePageSize?: number): string;
+    /**
+     * Drives the loop from the response-metadata envelope
+     * (`PersonsApiResponseMetadata` / `InsightApiResponseMetadata` / v2 `ResponseMetadata`):
+     * `next_link` is the vendor's own next-page URL. A short page (fewer records than requested) always
+     * terminates — the vendor emits `next_link` past the end of the dataset, so it is not a sufficient
+     * stop signal on its own.
+     */
+    protected ExtractPaginationInfo(rawBody: unknown, _paginationType: PaginationType, _currentPage: number, currentOffset: number, pageSize: number): PaginationState;
+    /** Reads the `skip` query param out of a vendor `next_link`, tolerating a relative URL. */
+    private ReadSkipParam;
+    /**
+     * Appends the object's declared incremental filter — `Configuration.watermarkParam`
+     * (`updated_since` / `created_since` / `archived_since`) — to every request of a watermarked
+     * object. Applied HERE rather than in {@link BuildPaginatedURL} so it also reaches non-paginated
+     * single-page fetches. Never invents a param name: silent metadata ⇒ full pull.
+     */
+    protected AppendDefaultQueryParams(url: string, obj: MJIntegrationObjectEntity): string;
+    /**
+     * Thin wrapper around the base's metadata-driven fetch. It (a) publishes the per-object response
+     * context the base's object-less `NormalizeResponse` signature can't carry, (b) bridges the frozen
+     * contract's `accessPath.parentObject` onto the key the base's parent resolver reads, (c) tracks the
+     * watermark high-water mark across the object's batches and emits it ONLY on the terminal batch, so
+     * a mid-pass failure (which throws before we return) leaves the stored watermark untouched.
+     */
+    FetchChanges(ctx: FetchContext): Promise<FetchBatchResult>;
+    /**
+     * Refuses a read against an object that declares NO read door, instead of letting the base compose a
+     * request against the API ROOT. rasa.io has one such object — `Lead Post` is write-only (`APIPath`
+     * empty, `CreateAPIPath: /v1/lead-posts`, Create+Update only) — and a caller that syncs "all objects"
+     * will ask it to read. Without this guard the empty path resolves to `GET {baseURL}/`, whose failure
+     * mode is worse than an error: if the vendor root ever answers 200 (a status/banner document), the
+     * envelope reader would treat that payload as this object's record set. Fail precisely and name the
+     * cause instead.
+     */
+    private AssertReadable;
+    /** GetRecord also runs NormalizeResponse — publish the same response context first. */
+    GetRecord(ctx: GetRecordContext): Promise<ExternalRecord | null>;
+    private IsFirstBatch;
+    /** Resolves and stores the extraction path + unwrap-verdict state for the object being fetched. */
+    private PublishResponseContext;
+    /**
+     * Composes the LIST path (`ResponseDataKey`) with the verdicted PER-RECORD unwrap path. The unwrap
+     * verdict is anchored at the list root, so `results` + `data` → `results[].data`, and
+     * `results[].topics` + `data.topics` → `results[].data.topics` (the probe's re-point: the declared
+     * fields live under `data`, not at the record root). No verdict ⇒ the declared key verbatim.
+     */
+    private EffectiveDataPath;
+    /**
+     * The frozen contract expresses an object's owner as `Configuration.accessPath.parentObject`; the
+     * base's template-var resolver reads `Configuration.parentObjectName`. Same declared fact, two
+     * spellings — bridged here (in memory only, never persisted) so a `{var}` path resolves its parent
+     * instead of returning PARENT_UNRESOLVED. Additive: an existing `parentObjectName` always wins.
+     */
+    private BridgeAccessPathToParentConfig;
+    /** Folds this batch's watermark-field values into the object's running high-water mark. */
+    private AdvanceWatermarkHighWater;
+    /** Terminal-batch watermark: the run's high-water mark, else the caller's value unchanged. */
+    private FinalWatermark;
+    /**
+     * The generic `CreateRecord` is used as-is; only ID extraction is vendor-shaped. rasa.io returns the
+     * new record inside the standard envelope — `PersonApiPostResponse.example` is
+     * `{ code, metadata, results: [ { id } ] }` — so the base's root-level `body.id` probe finds nothing.
+     * We look at `results[0]` and, when the per-record envelope is in play, `results[0].data`.
+     */
+    protected ExtractIDFromResponse(response: RESTResponse, idLocation: string | null): string | undefined;
+    /** Vendor error envelope: `metadata.errors` alongside the standard `code` / `status_code`. */
+    protected ExtractErrorMessage(response: RESTResponse): string | undefined;
+    /**
+     * Enumerates the object universe from rasa.io's PUBLICLY-PUBLISHED OpenAPI documents (both API
+     * generations), unioned with the persisted Declared metadata. Deliberately credential-free: the
+     * runtime structure self-check runs without a token, so standard objects MUST re-yield without one.
+     * A live credential is additive only (see {@link IntrospectSchema}). If the specs are unreachable the
+     * method degrades to the persisted set rather than failing the sync.
+     */
+    DiscoverObjects(companyIntegration: MJCompanyIntegrationEntity, contextUser: UserInfo): Promise<ExternalObjectSchema[]>;
+    /**
+     * Fields for one object: the persisted Declared set, unioned with every property the PUBLIC spec
+     * declares on the object's backing definitions (`Configuration.recordSchemas`). Credential-free —
+     * a token contributes nothing here. Declared entries win on collision; spec-only properties are
+     * appended so a vendor schema addition surfaces without a metadata re-extract.
+     */
+    DiscoverFields(companyIntegration: MJCompanyIntegrationEntity, objectName: string, contextUser: UserInfo): Promise<ExternalFieldSchema[]>;
+    /**
+     * Sample-union enrichment (MJ connector standard): after the cache-driven introspection, sample each
+     * object's LIVE read shape and union it into the declared field set — this is where a tenant's own
+     * custom person attributes reach the schema. Best-effort; a sample failure leaves the declared set
+     * untouched. Overrides `IntrospectSchema`, NOT `DiscoverFields` (which would recurse into
+     * `DiscoverFieldsViaFetch`'s own fallback).
+     *
+     * SEQUENTIAL, and that is load-bearing. {@link FetchChanges} publishes its per-object response
+     * context onto INSTANCE state (`responseCtx`/`currentWatermark`/`pendingWarnings`) which is read
+     * back AFTER the HTTP round-trip. Sampling the catalog with `Promise.all` therefore raced: every
+     * concurrent call overwrote `responseCtx`, so a response was normalized against some OTHER object's
+     * `DataPath`, matched nothing, and yielded ZERO records — cleanly, with no throw and no warning.
+     * Observed live: 17 of 18 objects that reached the sampler logged `rows=0 | cols: []`, the sole
+     * survivor being the one that happened to win the race, and the resulting all-null field widths
+     * were what made the framework's unknown-width defect drop 8,841 records. The sync engine iterates
+     * objects sequentially, which is why the identical read path works there. Do not re-parallelize
+     * this without first threading the response context through the call instead of the instance.
+     */
+    IntrospectSchema(companyIntegration: MJCompanyIntegrationEntity, contextUser: UserInfo): Promise<SourceSchemaInfo>;
+    /** Declared fields, tolerating an object the cache doesn't carry (a spec-only discovery). */
+    private SafeDeclaredFields;
+    /** The Swagger definition name(s) backing an object, per its declared `Configuration.recordSchemas`. */
+    private RecordSchemaNamesFor;
+    /** Reverse index: Swagger definition name → the Declared object that claims it. */
+    private IndexDeclaredObjectsByRecordSchema;
+    /**
+     * The set of doors (normalized endpoint paths) already served by a Declared object. Used to suppress
+     * spec-only "objects" that are really an alias of a Declared resource — see the door test in
+     * {@link DiscoverObjects}. Both the frozen contract's `accessPath.door` and the row's own `APIPath`
+     * are indexed, since either may carry the endpoint for a given object.
+     */
+    private IndexDeclaredDoors;
+    /**
+     * Canonical form of an endpoint path for identity comparison: version segment dropped (a Declared
+     * `APIPath` carries `/v1`|`/v2`; a Swagger 2.0 path key does not — the prefix lives in `basePath`),
+     * path parameters collapsed to `{}` (`/persons/{id}/topics` ≡ `/persons/{person_id}/topics`), and
+     * casing/trailing slashes normalized.
+     */
+    private NormalizeDoor;
+    /**
+     * Every ACTIVE IntegrationObject for this integration, read from the same engine cache the base
+     * class reads (`IntegrationEngineBase.GetActiveIntegrationObjects`). Empty when the engine has not
+     * been configured yet — discovery then degrades to the spec-only naming, never throws.
+     */
+    private ActiveObjects;
+    /**
+     * Fetches + merges rasa.io's public Swagger documents (v1 and v2) with NO credential, and walks
+     * every readable operation to enumerate RECORD TYPES (not entry points): each GET's success schema
+     * is resolved through the `{code, metadata, results[]}` envelope down to the item definition. Only
+     * the item type itself is yielded — nested `$ref`'d sub-objects are NOT promoted to record types
+     * (see {@link EnumerateRecordTypes}). Cached for the process lifetime.
+     */
+    private LoadPublicSpecs;
+    private FetchSpec;
+    /** Walks every readable operation in one document, yielding the record types it exposes. */
+    private EnumerateRecordTypes;
+    /** Descends the `{code, metadata, results[]}` envelope to the item definition name. */
+    private ResolveRecordDefinitionName;
+    private RefName;
+    /** Maps a Swagger definition's properties onto ExternalFieldSchema. Constraints come from the spec only. */
+    private FieldsFromDefinition;
+    /** Human-readable object name for a spec-only record type (`PersonsApiGetResponseItem` → `Persons`). */
+    private DeriveObjectName;
+    /**
+     * Proves the whole auth chain end-to-end: mint the JWT (step 1) and spend it on a read (step 2).
+     * Uses `/v1/communities` — the smallest documented readable surface every v1 credential can reach.
+     */
+    TestConnection(companyIntegration: MJCompanyIntegrationEntity, contextUser: UserInfo): Promise<ConnectionTestResult>;
+    /** Credential record first (the supported path), CompanyIntegration.Configuration as the fallback. */
+    private ParseConfig;
+    private ParseConfigFromCredential;
+    /** Case-insensitive key matching over the credential payload, then strict Zod validation. */
+    private NormalizeConfigValues;
+    /** Parses an IntegrationObject's Configuration JSON into the typed per-object shape. */
+    private ObjectConfig;
+    /** Narrows an unknown to a plain object record, or null. */
+    private AsRecord;
+}
+export {};