@opencxh/domain 1.224.0 → 1.225.0

package/dist/platform/provider.d.ts

@@ -102,10 +102,21 @@ export interface FileUploadPayload {
     mimeType: string;
     accountId?: string;
     path?: string;
+    /**
+     * Write only if the object still carries this version marker.
+     *
+     * The floor is the caller's own pre-check; this closes the window between
+     * that check and the write. A backend that does not support conditional
+     * writes ignores the field, so the pre-check has to stay - see the save
+     * handler in `apps/storage`.
+     */
+    ifMatch?: string;
 }
 export interface FileUploadResponse {
     id: string;
     url: string;
+    /** The version marker the object now carries, when the backend reported one. */
+    revision?: string;
 }
 export interface FileGetPayload {
     accountId?: string;

package/dist/platform/storage.d.ts

@@ -54,17 +54,23 @@ export interface FilePointer {
     size: number;
     ownerId: string;
     createdAt?: number;
+    /** When the backend last saw it change. Only set on a listing the backend owns. */
+    modifiedAt?: number;
     tags?: string[];
     /**
-     * Bumped on every write to the file's bytes. An editor reads it when it opens
-     * the file and presents it back on save; the save is a compare-and-set on this
-     * value, so a second writer is refused instead of silently overwriting.
+     * The version an editor read, handed back on save so a second writer is
+     * refused instead of silently overwriting.
+     *
+     * **Opaque to every reader.** It is a counter on a row the storage app owns
+     * and a version marker (an ETag) on a backend that owns its own tree, and no
+     * client does arithmetic on it - it is read when the file opens and presented
+     * back unchanged. Only the writer that minted it compares it.
      *
      * Optional because rows written before the field existed read back undefined,
      * and there is no `$exists` to find them. The first save on such a row is
      * unconditional and gives it one.
      */
-    revision?: number;
+    revision?: string | number;
 }
 /**
  * A field a storage provider needs to connect an account. Providers declare
@@ -78,12 +84,276 @@ export interface StorageAccountField {
     required?: boolean;
     placeholder?: string;
 }
+/**
+ * What a storage backend can actually do.
+ *
+ * Declared per provider rather than assumed, because the backends genuinely
+ * differ: a bucket has no rename (it is a copy plus a delete), a Graph drive
+ * has no notion of a base path, and FTP can do nothing at all in this runtime.
+ * The UI reads this instead of branching on a provider id, so a new backend
+ * needs no changes here.
+ *
+ * An empty array is a legitimate answer: "connected, but nothing works right
+ * now" is more useful than a button that fails on click.
+ */
+export type StorageCapability = 
+/** Read one object's bytes. */
+"get"
+/** Write one object's bytes. */
+ | "upload" | "delete"
+/** List one directory. Without it the backend cannot be browsed at all. */
+ | "list"
+/** Report one entry: the size, type and version marker of a single key. */
+ | "stat"
+/** Enumerate the locations an account can reach (a drive, a site, a bucket). */
+ | "roots"
+/**
+ * Move a key to another key. Whether that is atomic is the backend's business:
+ * a drive does a real move, a bucket copies and deletes.
+ */
+ | "rename"
+/** Materialise an empty directory. A bucket cannot; a drive can. */
+ | "create-folder"
+/** Answer a free-text query the store itself resolves. */
+ | "search"
+/** Give someone else access, at the backend, to a file we do not own the ACL of. */
+ | "share"
+/** Say who has access right now. */
+ | "share-list"
+/** Take an access away again. */
+ | "share-revoke"
+/** Say which earlier versions of a file the backend still holds. */
+ | "version-list"
+/** Read the bytes of one earlier version. */
+ | "version-get"
+/** Make an earlier version the current one again. */
+ | "version-restore";
+/** Who a share reaches. Deliberately no "anyone": see the plan for why. */
+export type ShareAudience = "people" | "organization";
+export type ShareRole = "read" | "write";
+/**
+ * One access that exists at the backend right now.
+ *
+ * Read back from the provider on every question rather than mirrored here. The
+ * backend owns the tree and it owns the ACL with it; a table of our own beside
+ * it would be a second, staler account of who can open a file - and the moment
+ * somebody changes it in OneDrive itself, ours would be wrong and confident.
+ */
+export interface ProviderShare {
+    /** The backend's own permission id. Opaque - only it knows what this means. */
+    id: string;
+    audience: ShareAudience;
+    role: ShareRole;
+    /** Who it reaches, as the backend names them. */
+    recipients: {
+        name?: string;
+        email?: string;
+    }[];
+    url?: string;
+    expiresAt?: number;
+    /**
+     * Granted on a folder further up, not on this file.
+     *
+     * You cannot take it back from here, so the UI shows it greyed and without a
+     * button instead of offering an action that 403s.
+     */
+    inherited?: boolean;
+}
+/** `POST /provider/storage/share` */
+export interface ProviderSharePayload {
+    accountId?: string;
+    root?: string;
+    key: string;
+    audience: ShareAudience;
+    role: ShareRole;
+    /** Addresses, already resolved by the storage app. Only for `people`. */
+    recipients?: string[];
+    expiresAt?: number;
+    message?: string;
+}
+export interface ProviderShareResult {
+    /** Present for a link share; a person-share sends an invitation instead. */
+    url?: string;
+    grants: ProviderShare[];
+}
+/** `POST /provider/storage/shares` and `/unshare`. */
+export interface ProviderSharesPayload {
+    accountId?: string;
+    root?: string;
+    key: string;
+}
+export interface ProviderUnsharePayload extends ProviderSharesPayload {
+    shareId: string;
+}
+/**
+ * One earlier state of a file.
+ *
+ * `id` is opaque and travels back to the provider verbatim: a drive mints a
+ * readable "3.0", a bucket an arbitrary token. Nobody else may parse it, and
+ * nobody may order on it - `modifiedAt` is the only orderable field.
+ *
+ * Everything past `modifiedAt` is optional because the two backends disagree on
+ * what a version even records: a drive knows who saved it, a bucket knows only
+ * that somebody did.
+ */
+export interface ProviderVersion {
+    id: string;
+    modifiedAt: number;
+    /** Absent where the backend does not report a size per version. */
+    size?: number;
+    /** Absent at a bucket: S3 records an owner id, not a person. */
+    author?: {
+        name?: string;
+        email?: string;
+    };
+    /** The version that is the file right now. One of them, or none. */
+    current?: boolean;
+    /** A marker that hides the key rather than a state of it: no bytes to read. */
+    deleted?: boolean;
+}
+/** `POST /provider/storage/versions` */
+export interface ProviderVersionsPayload {
+    accountId?: string;
+    root?: string;
+    key: string;
+}
+/** `POST /provider/storage/version-get` and `/provider/storage/version-restore`. */
+export interface ProviderVersionPayload extends ProviderVersionsPayload {
+    versionId: string;
+}
+export interface ProviderVersionsResult {
+    versions: ProviderVersion[];
+    /**
+     * False only where the backend *could* keep history but it is switched off -
+     * a bucket without versioning. A drive that always keeps it answers true with
+     * a single entry, and "no history yet" is a different sentence on screen than
+     * "history is off here".
+     */
+    enabled: boolean;
+}
 /** A connectable storage provider + the fields needed to connect an account. */
 export interface StorageProviderInfo {
     /** Storage-role provider id (e.g. base64("ftp:storage")). */
     id: string;
     displayName: string;
     accountFields: StorageAccountField[];
+    /**
+     * Empty when the provider still serves only the old, un-namespaced
+     * `/provider/describe` - that route predates capabilities and cannot report
+     * them, so "we do not know" and "nothing works" read the same here.
+     */
+    capabilities: StorageCapability[];
+    /** What a share may look like here; present only when `share` is declared. */
+    share?: StorageProviderDescription["share"];
+}
+/**
+ * The payload of `GET /provider/storage/describe`.
+ *
+ * A separate, namespaced route rather than a wider `/provider/describe`: an app
+ * serves exactly one bare describe, and an app that is also a communication
+ * provider has already spent it. This follows the convention already set by
+ * `/provider/sync/describe` and `/provider/scope/describe`.
+ */
+export interface StorageProviderDescription {
+    displayName: string;
+    accountFields: StorageAccountField[];
+    capabilities: StorageCapability[];
+    /**
+     * What a share may look like at this backend. Present only when `share` is
+     * declared; the dialog is built from it, so a backend that shares differently
+     * needs no UI changes here.
+     */
+    share?: {
+        audiences: ShareAudience[];
+        roles: ShareRole[];
+        /** May a share carry an expiry date? */
+        expiry: boolean;
+    };
+}
+/**
+ * One location an account can reach: a OneDrive, a SharePoint site, a bucket.
+ *
+ * The point of asking the provider instead of having someone type it in: one
+ * connected Microsoft account can reach a personal drive plus every site the
+ * person is a member of, and making an admin create a row per site per user
+ * does not scale and goes stale the moment access is revoked.
+ */
+export interface StorageRoot {
+    /**
+     * Opaque to the storage app - it travels back to the provider verbatim on
+     * every `list`. A provider is free to put a drive id, a site id, or nothing
+     * meaningful in it.
+     */
+    key: string;
+    name: string;
+    kind: "drive" | "site" | "library" | "bucket" | "shared";
+}
+/** `POST /provider/storage/roots` */
+export interface ProviderRootsPayload {
+    accountId?: string;
+}
+/** `POST /provider/storage/list` - one directory at the backend. */
+export interface ProviderListPayload {
+    accountId?: string;
+    /** A {@link StorageRoot.key}; empty means the account's own default root. */
+    root?: string;
+    /** Directory inside that root: leading slash, no trailing one. */
+    path?: string;
+    /** Opaque continuation token from a previous answer. */
+    cursor?: string;
+    /**
+     * Return the whole subtree instead of one directory.
+     *
+     * Only for the cross-location views ("Recent"), which ask a question no single
+     * directory answers. A provider that cannot do it is free to ignore the flag
+     * and return its normal listing - the caller then simply sees less, which is
+     * better than a second route that half the backends refuse.
+     */
+    recursive?: boolean;
+}
+/** `POST /provider/storage/rename` - move a key, returning the key it now has. */
+export interface ProviderRenamePayload {
+    accountId?: string;
+    root?: string;
+    key: string;
+    /** The full key it should have; the storage app builds it from path + name. */
+    newKey: string;
+}
+/** `POST /provider/storage/stat` - one entry, or null when it is not there. */
+export interface ProviderStatPayload {
+    accountId?: string;
+    root?: string;
+    /** The backend's own key, as handed out by `list`. */
+    key: string;
+}
+/**
+ * One entry in a directory, as the *backend* sees it.
+ *
+ * Deliberately not a {@link FilePointer}: a provider knows nothing about mounts,
+ * owners or the storage app's ids, and inventing them there would be the
+ * provider claiming things it cannot know. The storage app maps this into a
+ * `FilePointer` on the way out, which is where the id is minted.
+ */
+export interface ProviderEntry {
+    name: string;
+    type: "file" | "folder";
+    /** The backend's own key for this entry. Opaque to the storage app. */
+    key: string;
+    size: number;
+    /** Epoch millis; 0 when the backend did not say. */
+    modifiedAt: number;
+    /** Set only when the backend actually knows; the storage app guesses otherwise. */
+    mimeType?: string;
+    /**
+     * Version marker for a compare-and-set write (an S3 ETag, a Graph eTag).
+     * Absent means the backend offers no such guarantee.
+     */
+    revision?: string;
+}
+export interface ProviderListResult {
+    entries: ProviderEntry[];
+    /** Present when the directory was truncated; hand it back to continue. */
+    cursor?: string;
 }
 /**
  * A linked storage backend account (credentials to an S3 bucket, an FTP host, …).
@@ -93,6 +363,13 @@ export interface StorageProviderInfo {
 export interface StorageAccount {
     id: string;
     organizationId: string;
+    /**
+     * Whose credential this is. Absent means the organisation's, set means one
+     * person's - the single ownership axis on a credential, as
+     * `platform/account.ts` lays down. A location backed by a personal account
+     * can only ever be personal: sharing it would be lending out the token.
+     */
+    userId?: string;
     /** Account-provider id, e.g. base64("s3:account"). */
     providerId: string;
     displayName: string;

package/dist/platform/sync-source.d.ts

@@ -107,6 +107,16 @@ export interface SyncSourceDefinition {
      * failed one.
      */
     accountProviderId?: string;
+    /**
+     * The settings key that decides which kind this connection lands.
+     *
+     * Most sources know that at build time and list it in {@link SyncSourceDefinition.kinds}. A
+     * generic source does not: one MCP tool answers with one kind of thing, but *which* kind is a
+     * choice made per connection. Declaring the key here — rather than letting the UI guess that a
+     * setting called `kind` is special — keeps the mapping step showing the fields of the one kind
+     * this connection will actually produce, instead of every kind the source could ever land.
+     */
+    kindSetting?: string;
     /**
      * Settings that differ per connection and therefore do not belong in code.
      *
@@ -303,6 +313,24 @@ export interface SyncLandOutcome {
 export interface SyncLandResponse {
     outcomes: SyncLandOutcome[];
 }
+/**
+ * One field a target app accepts for a kind — the right-hand side of a column mapping.
+ *
+ * Deliberately **flat and scalar only**. A field that carries structure (a contact's endpoint
+ * list, a work item's assignees) cannot come out of a CSV column or a tool answer anyway, and
+ * declaring it would promise a mapping UI something it cannot render. An app that wants such a
+ * value mappable declares a scalar alias instead (`email`) and assembles the structure itself —
+ * that conversion belongs with the app that owns the shape, not in the pipeline.
+ */
+export interface SyncTargetField {
+    key: string;
+    label: string;
+    /** Missing after mapping ⇒ that one row fails, not the batch. */
+    required?: boolean;
+    type?: "text" | "number" | "boolean" | "date";
+    /** Explanation under the field in the mapping UI. */
+    help?: string;
+}
 /**
  * Bare payload of `GET /provider/sync/land-describe`: which kinds this app can land.
  *
@@ -313,7 +341,19 @@ export interface SyncLandResponse {
 export interface SyncTargetDescribe {
     source: string;
     kinds: string[];
+    /**
+     * Per kind, the fields a mapping may fill. Absent = this app does not support column mapping,
+     * and only a source that maps in code (`transport: "native"`) can feed it.
+     */
+    fields?: Record<string, SyncTargetField[]>;
 }
+/**
+ * The target field key that always has to be mapped, next to whatever the app declares.
+ *
+ * It is not in {@link SyncTargetDescribe.fields} because no app owns it: it is the dedupe axis of
+ * the pipeline itself. A mapping without it would land every row as a new one, every round.
+ */
+export declare const SYNC_MAPPING_EXTERNAL_ID = "externalId";
 /** How healthy a connection is. What the list shows as a badge. */
 export type SyncHealth = 
 /** Last run succeeded. */
@@ -352,6 +392,30 @@ export interface SyncConnection {
      * cursor: one schema field that has to be able to carry any shape.
      */
     settings?: Record<string, unknown>;
+    /**
+     * The field names this connection's source actually delivers — the left-hand side of the
+     * mapping UI.
+     *
+     * On the **connection** and not on the source definition, because that is where the truth is:
+     * for a CSV they are the column headers of *this* file, for a tool the keys of *this* answer.
+     * A static declaration on the source would have to lie about both.
+     */
+    rawFields?: string[];
+    /**
+     * Target field key → raw field name. Absent = the source maps in code and the runtime passes
+     * records through untouched, which is what every `native` source does.
+     */
+    mapping?: Record<string, string>;
+    /**
+     * Namespace stamped in front of every mapped external id (`hubspot` ⇒ `hubspot:5591`).
+     *
+     * A source that maps in code namespaces its own ids, and must: a bare `12345` from two systems
+     * is the same row as far as the dedupe index is concerned, so without this two connections
+     * would merge each other's records. A mapped source cannot do it itself — the mapping runs
+     * after the pull and is the thing that decides which field is the id — so the runtime does it,
+     * and the connection carries the namespace. Required as soon as a mapping exists.
+     */
+    externalIdPrefix?: string;
     /** Free-form name; absent = the source's label. */
     label?: string;
     mode: SyncMode;
@@ -410,6 +474,14 @@ export interface SyncRun {
     failed: number;
     /** Was this a sweep? Explains why `scanned` is suddenly much higher. */
     fullSweep?: boolean;
+    /**
+     * A trial round: mapped and checked, but nothing written and no cursor moved.
+     *
+     * It reads **one page**, on purpose — a dry run is a sample that answers "does this mapping
+     * hold up", not an import. `written` therefore stays 0 and the rows that would have landed are
+     * counted as `skipped`; only rows the mapping could not produce count as `failed`.
+     */
+    dryRun?: boolean;
     /** The error that stopped the whole run. Empty on `partial` — see {@link SyncRun.errors}. */
     error?: string;
     /**

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@opencxh/domain",
-  "version": "1.224.0",
+  "version": "1.225.0",
   "type": "module",
   "main": "./dist/index.js",
   "module": "./dist/index.js",