@opencxh/domain 1.228.0 → 1.231.0

package/dist/platform/connector.d.ts

@@ -13,7 +13,7 @@ export declare const CONNECTOR_PROVIDER_GROUP = "connector";
  * headline deliberately omits — a Jira issue has a description, comments and custom fields; a
  * To Do task has nothing the headline leaves out, and declares none.
  */
-export type ConnectorCapability = "list" | "get" | "fields" | "write" | "comment" | "options";
+export type ConnectorCapability = "list" | "get" | "fields" | "write" | "create" | "comment" | "attach" | "options";
 /**
  * Continuous or one-off — a real difference, not a label.
  *
@@ -191,6 +191,17 @@ export interface ConnectorListResponse {
     cursor?: unknown;
     /** No more data after this page. The runtime then does not chain on. */
     done: boolean;
+    /**
+     * "Everything of this kind I could still see" — handed to the landing app as-is.
+     *
+     * Only meaningful on the **last page of a full sweep**, which is the only moment a connector
+     * has enumerated exhaustively. See {@link SyncLandRequest.reconcile} for what the other side
+     * does with it, and why an incomplete list must be left absent rather than sent short.
+     */
+    reconcile?: {
+        kind: string;
+        seenExternalIds: string[];
+    };
     /**
      * The connector is rate-limited; wait at least this long before the next attempt.
      *
@@ -245,6 +256,50 @@ export interface ConnectorWriteResponse {
      */
     data: Record<string, unknown>;
 }
+/**
+ * `POST /provider/connector/create` — make a new record in the system that owns the container.
+ *
+ * The sibling of {@link ConnectorWriteRequest} and deliberately a separate route: a create has no
+ * `externalId` yet (it is what comes back) and it is addressed to a *container* instead of a
+ * record. Folding the two would make both fields optional, and "which of these two is missing"
+ * is exactly the kind of question a contract should not have to ask at runtime.
+ *
+ * Why this exists at all, given that proxy is "the truth stays with them": it is the same promise
+ * as a write. A screen that offers "new item" inside an imported project has to put that item
+ * where the work actually lives — the alternative is a local row with our own numbering sitting
+ * between theirs, invisible at the source and undone by nothing, for ever.
+ */
+export interface ConnectorCreateRequest {
+    /** → {@link ConnectorDefinition.id} */
+    sourceId: string;
+    connectionId: string;
+    /** The {@link ManagedAccount} to talk with. Absent when no credential is needed. */
+    accountId?: string;
+    settings?: Record<string, unknown>;
+    /** From {@link ConnectorDefinition.kinds}. */
+    kind: string;
+    /**
+     * Where the new record goes, in the source's own id space: the project, the board, the list.
+     *
+     * Required, and there is no "somewhere sensible" fallback. A connector that guessed a container
+     * would put work in a project nobody is looking at, and report success.
+     */
+    containerExternalId: string;
+    /** The new record, in the **target app's** field names — same vocabulary as `patch`. */
+    data: Record<string, unknown>;
+}
+/**
+ * Answer to `POST /provider/connector/create`. Wrapped in `ResponseFactory`.
+ *
+ * Identical in shape to {@link ConnectorWriteResponse} on purpose: the caller lands both through
+ * the same upsert, so the record it gets back carries the source's id and the source's version of
+ * every field it filled in itself — a key, a workflow's opening status, a default type.
+ */
+export interface ConnectorCreateResponse {
+    /** The id the source gave it. This is what makes the new row findable on the next round. */
+    externalId: string;
+    data: Record<string, unknown>;
+}
 /**
  * One editable field of a **record**, as the connector describes it.
  *
@@ -351,11 +406,37 @@ export interface ConnectorComment {
     /** Epoch ms. */
     createdAt?: number;
 }
+/**
+ * One attachment on a record — its **description**, never its bytes.
+ *
+ * Metadata is cheap and a list of it is what a screen draws; the file itself is fetched only
+ * when somebody asks for it, over `POST /provider/connector/attachment`. Sending bytes with the
+ * detail would put every attachment of every opened issue on the wire.
+ */
+export interface ConnectorAttachment {
+    /** The source's own id, and what the fetch route is addressed with. */
+    id: string;
+    filename: string;
+    mimeType: string;
+    /** Bytes. Absent when the source does not say, which is not the same as zero. */
+    size?: number;
+    /** The author's display name, like {@link ConnectorComment.author}. */
+    author?: string;
+    /** Epoch ms. */
+    createdAt?: number;
+}
 /** Answer to `POST /provider/connector/get`. Wrapped in `ResponseFactory`. */
 export interface ConnectorGetResponse {
     /** Plain text. Empty is a valid answer and means the record has none. */
     description?: string;
     comments?: ConnectorComment[];
+    /**
+     * What hangs off this record at the source. Metadata only — see {@link ConnectorAttachment}.
+     *
+     * Beside `comments` because it is the same kind of thing: shown while the screen is open,
+     * never stored. A proxy row holds no truth, and an attachment is the least storable part of it.
+     */
+    attachments?: ConnectorAttachment[];
     /** A deep link into the source system, so a person can always go to the real thing. */
     url?: string;
     /**
@@ -369,6 +450,64 @@ export interface ConnectorGetResponse {
         value: string;
     }[];
 }
+/**
+ * `POST /provider/connector/attachment` — fetch one attachment's bytes.
+ *
+ * Separate from `get` for the reason stated on {@link ConnectorAttachment}: the list is drawn
+ * every time a record opens, the bytes only when somebody clicks. A vendor's own content URL is
+ * not an answer here — it needs the vendor's credential, which lives on the connection and not
+ * in a browser.
+ */
+export interface ConnectorAttachmentRequest {
+    /** → {@link ConnectorDefinition.id} */
+    sourceId: string;
+    connectionId: string;
+    /** The {@link ManagedAccount} to talk with. Absent when no credential is needed. */
+    accountId?: string;
+    settings?: Record<string, unknown>;
+    /** From {@link ConnectorDefinition.kinds}. */
+    kind: string;
+    /** The record the attachment hangs on. */
+    externalId: string;
+    /** → {@link ConnectorAttachment.id} */
+    attachmentId: string;
+}
+/**
+ * Answer to `POST /provider/connector/attachment`. Wrapped in `ResponseFactory`.
+ *
+ * **base64**, because the hop to the browser is JSON either way and a single encoding across all
+ * three hops is one fewer place to get it wrong. The same choice comms made for mail attachments.
+ */
+export interface ConnectorAttachmentResponse {
+    filename: string;
+    mimeType: string;
+    base64: string;
+}
+/**
+ * `POST /provider/connector/attach` — add a file to a record at the source.
+ *
+ * The write half of the `attach` capability, and it throws on refusal like every other writer:
+ * an upload that silently did not arrive leaves the person believing the file is where it is not.
+ */
+export interface ConnectorAttachRequest {
+    /** → {@link ConnectorDefinition.id} */
+    sourceId: string;
+    connectionId: string;
+    /** The {@link ManagedAccount} to talk with. Absent when no credential is needed. */
+    accountId?: string;
+    settings?: Record<string, unknown>;
+    /** From {@link ConnectorDefinition.kinds}. */
+    kind: string;
+    externalId: string;
+    filename: string;
+    mimeType: string;
+    /** base64, for the reason on {@link ConnectorAttachmentResponse}. */
+    base64: string;
+}
+/** Answer to `POST /provider/connector/attach`: the attachment as the source now has it. */
+export interface ConnectorAttachResponse {
+    attachment: ConnectorAttachment;
+}
 /**
  * `POST /provider/connector/options` — the choices for one settings field.
  *

package/dist/platform/sync.d.ts

@@ -76,6 +76,23 @@ export interface SyncLandRequest {
      */
     proxy?: boolean;
     records: SyncRecord[];
+    /**
+     * "These are all the records of this kind I could see. Anything else of mine is gone."
+     *
+     * The answer to a deletion a source cannot report. A cursor on `updated` sees edits and new
+     * records; a delete leaves no trace it will ever return, and neither does a permission change
+     * that makes a record invisible. So the reconcile sweep says what it *did* see, and the landing
+     * app — the only side that knows what it holds — works out the difference.
+     *
+     * Sent once, on the last page of a sweep, next to the records of that page. A connector that
+     * cannot enumerate exhaustively must leave this absent: an incomplete list here reads as a mass
+     * deletion, which is the one failure worse than a stale row.
+     */
+    reconcile?: {
+        /** From `ConnectorDefinition.kinds`. One kind per reconcile — a sweep may send several. */
+        kind: string;
+        seenExternalIds: string[];
+    };
 }
 /** What happened to one record. */
 export interface SyncLandOutcome {

package/package.json

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