nucleus-core-ts 0.9.821 → 0.9.822

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/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`. */

package/package.json

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