nucleus-core-ts 0.9.821 → 0.9.823

package/dist/src/ElysiaPlugin/routes/integrations/inspect.d.ts

@@ -81,6 +81,7 @@ export declare function previewRun(chain: ResolvedChain, tokenCache: TokenCache,
     readEntityColumn: (entity: string, field: string) => Promise<unknown[]>;
     requiredFields: (entity: string) => string[];
     uniqueFields: (entity: string) => string[];
+    readEntityIdsBy: (entity: string, field: string) => Promise<Record<string, string>>;
 }, deps?: {
     fetchImpl?: typeof fetch;
     maxRecords?: number;

package/dist/src/ElysiaPlugin/routes/integrations/repository.d.ts

@@ -12,6 +12,7 @@ import type { EndpointSpec } from 'src/Services/Integrations/collect';
 import type { SourceConnection } from 'src/Services/Integrations/fetcher';
 import type { OAuthConfig } from 'src/Services/Integrations/oauth';
 import type { MappingSpec, RunRepository } from 'src/Services/Integrations/runner';
+import type { TransferDocument } from 'src/Services/Integrations/transfer';
 import type { PreImage } from 'src/Services/Integrations/writer';
 import type { Logger } from 'src/Services/Logger';
 import type { NucleusTable } from 'src/types';
@@ -75,6 +76,41 @@ export declare function resolveEndpointContext(deps: RepositoryDeps, by: {
  */
 export declare function cacheEndpointSample(deps: RepositoryDeps, endpointId: string, records: readonly unknown[]): Promise<void>;
 /** Columns of a target that must carry a value, for pre-write validation. */
+/**
+ * Everything one connection is made of, for an export.
+ *
+ * Read as three plain selects rather than through `resolveChain`, which starts
+ * from a mapping — a connection worth exporting may have endpoints and no
+ * mappings yet, and that is a legitimate thing to move.
+ */
+export declare function readConnectionBundle(deps: RepositoryDeps, sourceId: string): Promise<{
+    source: Record<string, unknown>;
+    endpoints: Record<string, unknown>[];
+    mappings: Record<string, unknown>[];
+} | null>;
+/**
+ * Writes an exported connection into this installation.
+ *
+ * Matched by NAME throughout — the connection by its slug, endpoints and
+ * mappings by their name — so bringing the same file in twice updates what is
+ * here instead of leaving two of everything. That is the behaviour somebody
+ * actually wants: the file is how a configuration is kept in step between two
+ * environments, not a one-shot.
+ *
+ * Credentials are neither in the file nor invented here. A connection arrives
+ * unable to authenticate, and says so, rather than arriving with an empty token
+ * that looks configured.
+ */
+export declare function applyTransferDocument(deps: RepositoryDeps, document: TransferDocument, userId: string): Promise<{
+    ok: true;
+    sourceId: string;
+    created: boolean;
+    endpoints: number;
+    mappings: number;
+} | {
+    ok: false;
+    error: string;
+}>;
 export declare function requiredFieldsOf(entities: NucleusTable[], targetEntity: string): string[];
 /**
  * Columns the target enforces as unique, single-column only.

package/dist/src/Services/Integrations/plan.d.ts

@@ -11,7 +11,7 @@
  * second implementation that drifts. And every rule about destroying data is
  * testable here without a database.
  */
-import type { MappedRecord, MissingRecordPolicy, ReferenceCheck, ReferenceInsert, RunIssue, RunPlan, WriteMode } from './types';
+import type { AccountInsert, AccountRule, MappedRecord, MissingRecordPolicy, ReferenceCheck, ReferenceInsert, RunIssue, RunPlan, WriteMode } from './types';
 /** A row already in the target table. */
 export type ExistingRow = {
     id: string;
@@ -35,6 +35,13 @@ export type WriteOperations = {
      * them. Empty unless a reference is set to `create`.
      */
     referenceInserts: ReferenceInsert[];
+    /**
+     * Accounts a run would create so its records have a login.
+     *
+     * Written before the records that point at them, in the same transaction: the
+     * person and their account both exist, or neither does.
+     */
+    accountInserts: AccountInsert[];
     updates: UpdateOp[];
     /** Rows to remove — from `replace`, or from the `delete` missing policy. */
     deletes: ExistingRow[];
@@ -76,6 +83,16 @@ export type PlanInput = {
      * required field, because the column is filled — just not by the source.
      */
     createDefaults?: Readonly<Record<string, unknown>>;
+    /** Creates an account alongside each new record, and links it. */
+    accountRule?: AccountRule | null;
+    /**
+     * Accounts that already exist, keyed by their match value.
+     *
+     * Loaded by the caller, like reference values: a record whose e-mail already
+     * has an account is LINKED to it rather than given a second one, which is what
+     * makes re-running an import safe.
+     */
+    existingAccounts?: Readonly<Record<string, string>>;
     /** Columns whose value has to already exist in another table. */
     references?: readonly ReferenceCheck[];
     /**

package/dist/src/Services/Integrations/runner.d.ts

@@ -24,7 +24,7 @@ import { type EndpointSpec } from './collect';
 import type { FetchImpl, SourceConnection } from './fetcher';
 import { type OAuthConfig, type TokenCache } from './oauth';
 import { type ExistingRow } from './plan';
-import type { FieldMapping, MissingRecordPolicy, ReferenceCheck, RunFailure, RunIssue, RunPlan, RunProgress, WriteMode } from './types';
+import type { AccountRule, FieldMapping, MissingRecordPolicy, ReferenceCheck, RunFailure, RunIssue, RunPlan, RunProgress, WriteMode } from './types';
 import { type PreImage, type WriterDeps } from './writer';
 /** The mapping being run, resolved from the database by the caller. */
 export type MappingSpec = {
@@ -47,6 +47,8 @@ export type MappingSpec = {
      * accounts must not also leave the key to them lying in a config table.
      */
     passwordColumn?: string | null;
+    /** Creates a login alongside each new record, in the same transaction. */
+    accountRule?: AccountRule | null;
 };
 /** Everything a run needs, already read and decrypted. */
 export type RunContext = {
@@ -67,6 +69,12 @@ export type RunContext = {
      * handles a plaintext secret, and never persisted: it belongs to this run.
      */
     createDefaults?: Record<string, unknown>;
+    /**
+     * The shared opening password, already hashed.
+     *
+     * Prepared by the caller so nothing in the engine handles a plaintext secret.
+     */
+    accountPasswordHash?: string | null;
 };
 /** Persistence and lookups the runner needs. Injected so it can be tested. */
 export type RunRepository = {
@@ -96,6 +104,8 @@ export type RunRepository = {
     readExistingRows(targetEntity: string): Promise<ExistingRow[]>;
     /** Distinct values of one column, for an `entity` parameter binding. */
     readEntityColumn(entity: string, field: string): Promise<unknown[]>;
+    /** `value → id` for one column, so an existing account can be linked rather than doubled. */
+    readEntityIdsBy(entity: string, field: string): Promise<Record<string, string>>;
     /** NOT NULL, no-default columns of the target. */
     requiredFields(targetEntity: string): string[];
     /** Single-column unique constraints of the target. */
@@ -128,6 +138,8 @@ export type RunOutcome = {
     failure: RunFailure | null;
     plan: RunPlan | null;
     created: number;
+    /** Accounts created so this run's records have a login. */
+    accountsCreated: number;
     /** Rows added to OTHER tables so this run's records could point at them. */
     referencesCreated: number;
     updated: number;

package/dist/src/Services/Integrations/transfer.d.ts

@@ -0,0 +1,123 @@
+/**
+ * Moving a whole integration between installations.
+ *
+ * A connection is not one record. It is a connection, the calls it makes, the
+ * parameters those calls take from each other, and the mappings that turn the
+ * answers into rows — and rebuilding that by hand in a second environment is
+ * both hours of work and a fresh chance to get one field wrong in a way nobody
+ * notices until an import writes it.
+ *
+ * So it travels as one document.
+ *
+ * ## What deliberately does NOT travel
+ *
+ * Every secret. Tokens, client secrets, OAuth passwords: none of them are in the
+ * document, and the import asks for them again on the other side. A file that
+ * carries credentials is a file that gets mailed, pasted into a ticket and
+ * committed — and the whole point of storing them encrypted is undone by one
+ * convenient export.
+ *
+ * ## Why names, not identifiers
+ *
+ * An endpoint's parameters can be bound to another endpoint, and a mapping reads
+ * from one. Those are foreign keys, and a foreign key means nothing in a
+ * database that has never seen it. On the way out they become the endpoint's
+ * NAME; on the way in they are looked up again. So a document stays valid across
+ * installations, and a re-import onto an existing connection updates what is
+ * there rather than duplicating it.
+ */
+import type { FieldMapping, MissingRecordPolicy, ReferenceCheck, WriteMode } from './types';
+/** Bumped only when an older document could be READ wrongly, not merely partially. */
+export declare const TRANSFER_VERSION = 1;
+export type TransferEndpoint = {
+    /** Unique within the document; how bindings and mappings refer to it. */
+    name: string;
+    method: string;
+    path: string;
+    description?: string | null;
+    queryParams?: Record<string, unknown> | null;
+    requestBody?: Record<string, unknown> | null;
+    responseRootPath?: string | null;
+    pagination?: Record<string, unknown> | null;
+    /** `endpointId` is replaced by `endpointName`; every other form is unchanged. */
+    paramBindings?: Record<string, unknown>[] | null;
+    enabled?: boolean;
+};
+export type TransferMapping = {
+    name: string;
+    /** The endpoint this mapping reads, by name. */
+    endpointName: string | null;
+    targetEntity: string;
+    fieldMappings: FieldMapping[];
+    referenceChecks?: ReferenceCheck[];
+    dedupSourceField?: string | null;
+    dedupTargetField?: string | null;
+    writeMode: WriteMode;
+    missingRecordPolicy: MissingRecordPolicy;
+    missingRecordColumn?: string | null;
+    missingRecordValue?: string | null;
+    passwordTargetColumn?: string | null;
+    enabled?: boolean;
+};
+export type TransferDocument = {
+    version: number;
+    /** Stamped by the caller; the engine has no clock of its own to trust. */
+    exportedAt?: string;
+    connection: {
+        name: string;
+        slug: string;
+        baseUrl: string;
+        description?: string | null;
+        authType: string;
+        authHeaderName?: string | null;
+        authQueryParam?: string | null;
+        extraHeaders?: Record<string, string> | null;
+        tokenUrl?: string | null;
+        oauthGrantType?: string | null;
+        oauthClientId?: string | null;
+        oauthUsername?: string | null;
+        oauthScope?: string | null;
+        oauthClientAuth?: string | null;
+        tlsVerify?: boolean;
+        timeoutMs?: number | null;
+        enabled?: boolean;
+    };
+    endpoints: TransferEndpoint[];
+    mappings: TransferMapping[];
+    /**
+     * Named so the person opening the file knows what it cannot do on its own.
+     * Read by nothing; it exists to be read by a human.
+     */
+    secretsExcluded: true;
+};
+/** True when a row carries something that must not be exported. Used by tests. */
+export declare function hasSecret(row: Record<string, unknown>): boolean;
+/**
+ * Builds the document from rows as they are stored.
+ *
+ * Field by field rather than by spreading the row: a column added to the table
+ * later — including the next encrypted one — must not ride out to a file simply
+ * because nobody updated this function.
+ */
+export declare function buildTransferDocument(input: {
+    source: Record<string, unknown>;
+    endpoints: Record<string, unknown>[];
+    mappings: Record<string, unknown>[];
+    exportedAt?: string;
+}): TransferDocument;
+export type TransferProblem = {
+    path: string;
+    message: string;
+};
+/**
+ * Checks a document before anything is written.
+ *
+ * Refusing a bad file costs one message; accepting one costs a half-built
+ * connection that looks configured and imports nothing — or worse, imports into
+ * the wrong table.
+ */
+export declare function validateTransferDocument(value: unknown): {
+    ok: boolean;
+    document: TransferDocument | null;
+    problems: TransferProblem[];
+};

package/dist/src/Services/Integrations/transfer.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/src/Services/Integrations/types.d.ts

@@ -11,7 +11,9 @@ export type MappingTransform = 'none' | 'trim' | 'upper' | 'lower' | 'toString'
 /** Folds accents, lowercases, and removes what an address cannot contain. */
  | 'emailSafe'
 /** The last part of a path-like value: `A/B/C` → `C`. */
- | 'pathLeaf';
+ | 'pathLeaf'
+/** Wraps a value as a list, for a column that holds one: `100712` → `['100712']`. */
+ | 'toList';
 /** One field of a mapping: external `source` path → internal `target` column. */
 export type FieldMapping = {
     /** Dot-path into the external record, e.g. `employeeNo` or `department.code`. */
@@ -133,7 +135,7 @@ export type RunStatus = 'queued' | 'running' | 'succeeded' | 'failed' | 'cancell
  */
 export type RunIssue = {
     sourceIndex: number;
-    kind: 'missing_required' | 'missing_dedup_key' | 'duplicate_in_batch' | 'duplicate_value' | 'invalid_value' | 'unmapped' | 'missing_reference';
+    kind: 'missing_required' | 'missing_dedup_key' | 'duplicate_in_batch' | 'duplicate_value' | 'invalid_value' | 'unmapped' | 'missing_reference' | 'account_unmatched';
     message: string;
     dedupKey?: string | null;
     /**
@@ -189,6 +191,47 @@ export type ReferenceCheck = {
     entityColumn: string;
     onMissing: ReferenceOnMissing;
 };
+/**
+ * An account created alongside each imported record.
+ *
+ * A directory carries people, not logins. Importing eight hundred employees and
+ * then creating eight hundred accounts by hand — matching them up by e-mail, one
+ * at a time — is the job nobody does, so the import that was supposed to save the
+ * afternoon produces a table of people who cannot sign in.
+ *
+ * So the account is part of the same import and the same transaction: either the
+ * person and their login both exist, or neither does.
+ *
+ * The password is NOT here. It belongs to the run — asked for once, used for
+ * every account that run creates, and stored nowhere. A password on a mapping is
+ * a password that outlives the reason for it.
+ */
+export type AccountRule = {
+    /** Entity the account row goes into, e.g. `users`. */
+    entity: string;
+    /** Column on the TARGET entity that receives the account's id, e.g. `userId`. */
+    idColumn: string;
+    /** Column on the account entity that identifies it, e.g. `email`. */
+    matchColumn: string;
+    /** Column of the MAPPED record whose value is matched against it. */
+    matchFrom: string;
+    /** Column on the account entity that receives the run's shared password. */
+    passwordColumn: string;
+    /** Other columns to fill on a new account, taken from the mapped record. */
+    values?: {
+        column: string;
+        from: string;
+    }[];
+};
+/** An account a run would create so an imported record has a login. */
+export type AccountInsert = {
+    entity: string;
+    /** What identifies it, so a row can be matched back to the record that needs it. */
+    matchColumn: string;
+    matchValue: string;
+    /** Everything to write, except the password the writer adds. */
+    data: Record<string, unknown>;
+};
 /** A value a run would add to a referenced table so a record can point at it. */
 export type ReferenceInsert = {
     entity: string;
@@ -251,6 +294,8 @@ export type RunPlan = {
      * approving, not read about afterwards.
      */
     referenceInserts: ReferenceInsert[];
+    /** Accounts this run would create so its records have a login. */
+    accountsToCreate: number;
     /** A few mapped rows so an operator can eyeball the mapping before committing. */
     sample: Record<string, unknown>[];
 };

package/dist/src/Services/Integrations/writer.d.ts

@@ -80,6 +80,28 @@ export type ApplyInput = {
     ops: WriteOperations;
     targetEntity: string;
     userId: string;
+    /**
+     * How an account is created alongside each record, and where its id goes.
+     *
+     * The password arrives already hashed: nothing in the engine handles a
+     * plaintext secret, and it is never written anywhere but the account row.
+     */
+    account?: {
+        idColumn: string;
+        /** Column on the ACCOUNT row that identifies it. */
+        matchColumn: string;
+        /**
+         * Column of the RECORD carrying the same value.
+         *
+         * Not the same thing as `matchColumn`, even when they share a name: one
+         * names a column on `users`, the other a column on `employees`, and reading
+         * the record with the account's column name is how a rename in either table
+         * would start handing people each other's logins.
+         */
+        matchFrom: string;
+        passwordColumn: string;
+        passwordHash: string;
+    } | null;
     /** Ownership predicates from the caller's claims. ANDed onto updates/deletes. */
     scopeConditions?: SQL[];
     /** Column and value written to rows the source no longer carries. */
@@ -91,6 +113,8 @@ export type ApplyInput = {
 export type ApplyResult = {
     ok: true;
     created: number;
+    /** Accounts created so this run's records have a login. */
+    accountsCreated: number;
     /** Rows added to OTHER tables so this run's records could point at them. */
     referencesCreated: number;
     updated: number;

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "nucleus-core-ts",
-	"version": "0.9.821",
+	"version": "0.9.823",
 	"description": "Production-ready, enterprise-grade TypeScript framework for building multi-tenant APIs",
 	"author": "Hidayet Can Özcan <hidayetcan@gmail.com>",
 	"license": "SEE LICENSE IN LICENSE",

package/src/system.tables.json

@@ -5331,6 +5331,11 @@
           "length": 100,
           "comment": "Column that receives the shared opening password given at run time. The password itself is never stored."
         },
+        {
+          "name": "account_rule",
+          "type": "jsonb",
+          "comment": "Creates a login alongside each imported record, in the same transaction, and links it. The password belongs to the run, never to this row."
+        },
         { "name": "schedule_cron", "type": "varchar", "length": 120 },
         {
           "name": "schedule_timezone",
@@ -5411,6 +5416,13 @@
           "default": 0,
           "comment": "Rows this run added to OTHER tables so its records could point at them."
         },
+        {
+          "name": "accounts_created_count",
+          "type": "integer",
+          "notNull": true,
+          "default": 0,
+          "comment": "Logins this run created so its records could be signed in to."
+        },
         { "name": "updated_count", "type": "integer", "notNull": true, "default": 0 },
         { "name": "skipped_count", "type": "integer", "notNull": true, "default": 0 },
         { "name": "deleted_count", "type": "integer", "notNull": true, "default": 0 },