@wildo-ai/external-connectors-models 1.1.10 → 1.1.12

package/dist/esm/protocols/subject-erasure-effect.standard-interface.js

@@ -0,0 +1,61 @@
+/**
+ * Standard Subject Erasure Effect Interface (#2006)
+ * --------
+ * The contract a PROVIDER implements so a subject erasure reaches what its vendor keeps about the erased
+ * person. It is what a provider's `complianceProfile.subjectErasure.stance = EXTERNAL_ERASURE_OPERATION`
+ * promises. Before this, only the engine could register such an effect (the billing provider, an HTTP_API
+ * resource), so a provider PACKAGE that honestly declared the stance was reported NOT_REGISTERED at every
+ * erasure.
+ *
+ * ## What the effect receives, and what it does not
+ *
+ * The effect receives the subject's IDENTIFIERS AT THIS VENDOR, and a way to call this provider's own
+ * operations. It never receives an execution context, a credential, the subject's personal fields, or any
+ * way to read the application's data:
+ *
+ * - **The references are read by the engine**, from the resource fields the OPERATOR declared hold them
+ *   (`providerComplianceChoices.<ref>.subjectReferences` in `wildo.saas.config.ts`). A provider package does not
+ *   know the application's resources, and an open read door into them would hand third-party-authored code
+ *   every row the application keeps. The engine reads them BEFORE the local scrub, because afterwards the
+ *   subject's row is erased and hidden.
+ * - **`execute` calls this provider's operations only, on the APPLICATION's connection.** The erasure is the
+ *   operator's obligation, so it spends the operator's account at the vendor. The call goes through the
+ *   engine's operation executor like any provider call: recorded, rate-budgeted, attributed to this package.
+ *
+ * ## Why the effect reports no status
+ *
+ * The engine derives the outcome from the calls IT recorded through `execute`: every call succeeded →
+ * COMPLETED, some → PARTIAL, none → FAILED, and an effect that made no call while there were references to
+ * erase → FAILED. A package therefore cannot report an erasure it did not perform. `execute` never throws: a
+ * vendor error comes back as `{ ok: false }`, so one failing call cannot abort the others, and nothing a
+ * vendor already applied is replayed.
+ *
+ * ## A vendor that finishes the deletion later, or holds nothing (#2181)
+ *
+ * Some vendors accept a deletion and carry it out on their own schedule: PostHog answers `202` and clears a person's
+ * events in a weekly job. Reporting that call COMPLETED would say the data is gone while it is still there. So a call
+ * may declare the vendor's published completion window (`vendorCompletion`), and may read the vendor's answer
+ * (`readAnswer`) to say what that answer reports: erased, queued, nothing held, or not erased. The engine still
+ * decides the outcome, from those recorded answers: a queued deletion makes the effect COMPLETES_AT_VENDOR with the
+ * window's lapse, a call whose every answer was "nothing held" makes it NOTHING_TO_ERASE, and an answer the reader
+ * cannot classify, or classifies as not erased, is a FAILED call. A reader can only describe an answer the engine
+ * received from a call it made; it never invents one.
+ */
+/** What a vendor's successful answer to one erasure call reports, as the call's `readAnswer` classifies it. */
+export var ProviderSubjectErasureVendorAnswer;
+(function (ProviderSubjectErasureVendorAnswer) {
+    /** The vendor erased what it held under the reference, in this call. */
+    ProviderSubjectErasureVendorAnswer["ERASED"] = "erased";
+    /**
+     * The vendor ACCEPTED the deletion and finishes it on its own schedule. Requires the call's `vendorCompletion`
+     * window: the erasure then reports COMPLETES_AT_VENDOR, by the instant the window lapses. Without a window the
+     * answer is treated as NOT_ERASED, because nothing bounds when the data leaves.
+     */
+    ProviderSubjectErasureVendorAnswer["QUEUED"] = "queued";
+    /** The vendor holds nothing under the reference. Every call answering this makes the effect NOTHING_TO_ERASE. */
+    ProviderSubjectErasureVendorAnswer["NOTHING_HELD"] = "nothing-held";
+    /** The vendor answered with a success status but reports it did not erase (a per-record failure inside a 2xx). */
+    ProviderSubjectErasureVendorAnswer["NOT_ERASED"] = "not-erased";
+})(ProviderSubjectErasureVendorAnswer || (ProviderSubjectErasureVendorAnswer = {}));
+/** @wildo_source:part:end external-connectors.models.subject-erasure-effect */
+//# sourceMappingURL=subject-erasure-effect.standard-interface.js.map

package/dist/esm/protocols/subject-erasure-effect.standard-interface.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"subject-erasure-effect.standard-interface.js","sourceRoot":"","sources":["../../../src/protocols/subject-erasure-effect.standard-interface.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA0CG;AAQH,+GAA+G;AAC/G,MAAM,CAAN,IAAY,kCAaX;AAbD,WAAY,kCAAkC;IAC5C,wEAAwE;IACxE,uDAAiB,CAAA;IACjB;;;;OAIG;IACH,uDAAiB,CAAA;IACjB,iHAAiH;IACjH,mEAA6B,CAAA;IAC7B,kHAAkH;IAClH,+DAAyB,CAAA;AAC3B,CAAC,EAbW,kCAAkC,KAAlC,kCAAkC,QAa7C;AA0ED,+EAA+E","sourcesContent":["/**\n * Standard Subject Erasure Effect Interface (#2006)\n * --------\n * The contract a PROVIDER implements so a subject erasure reaches what its vendor keeps about the erased\n * person. It is what a provider's `complianceProfile.subjectErasure.stance = EXTERNAL_ERASURE_OPERATION`\n * promises. Before this, only the engine could register such an effect (the billing provider, an HTTP_API\n * resource), so a provider PACKAGE that honestly declared the stance was reported NOT_REGISTERED at every\n * erasure.\n *\n * ## What the effect receives, and what it does not\n *\n * The effect receives the subject's IDENTIFIERS AT THIS VENDOR, and a way to call this provider's own\n * operations. It never receives an execution context, a credential, the subject's personal fields, or any\n * way to read the application's data:\n *\n * - **The references are read by the engine**, from the resource fields the OPERATOR declared hold them\n *   (`providerComplianceChoices.<ref>.subjectReferences` in `wildo.saas.config.ts`). A provider package does not\n *   know the application's resources, and an open read door into them would hand third-party-authored code\n *   every row the application keeps. The engine reads them BEFORE the local scrub, because afterwards the\n *   subject's row is erased and hidden.\n * - **`execute` calls this provider's operations only, on the APPLICATION's connection.** The erasure is the\n *   operator's obligation, so it spends the operator's account at the vendor. The call goes through the\n *   engine's operation executor like any provider call: recorded, rate-budgeted, attributed to this package.\n *\n * ## Why the effect reports no status\n *\n * The engine derives the outcome from the calls IT recorded through `execute`: every call succeeded →\n * COMPLETED, some → PARTIAL, none → FAILED, and an effect that made no call while there were references to\n * erase → FAILED. A package therefore cannot report an erasure it did not perform. `execute` never throws: a\n * vendor error comes back as `{ ok: false }`, so one failing call cannot abort the others, and nothing a\n * vendor already applied is replayed.\n *\n * ## A vendor that finishes the deletion later, or holds nothing (#2181)\n *\n * Some vendors accept a deletion and carry it out on their own schedule: PostHog answers `202` and clears a person's\n * events in a weekly job. Reporting that call COMPLETED would say the data is gone while it is still there. So a call\n * may declare the vendor's published completion window (`vendorCompletion`), and may read the vendor's answer\n * (`readAnswer`) to say what that answer reports: erased, queued, nothing held, or not erased. The engine still\n * decides the outcome, from those recorded answers: a queued deletion makes the effect COMPLETES_AT_VENDOR with the\n * window's lapse, a call whose every answer was \"nothing held\" makes it NOTHING_TO_ERASE, and an answer the reader\n * cannot classify, or classifies as not erased, is a FAILED call. A reader can only describe an answer the engine\n * received from a call it made; it never invents one.\n */\n\n/** @wildo_source:part:start external-connectors.models.subject-erasure-effect facet:kind:api facet:audience:app-developer */\n/** The answer to one call an erasure effect made through `execute`. A vendor error is a value, never a throw. */\nexport type ProviderSubjectErasureCallResult =\n  | { readonly ok: true; readonly output: unknown }\n  | { readonly ok: false; readonly error: string };\n\n/** What a vendor's successful answer to one erasure call reports, as the call's `readAnswer` classifies it. */\nexport enum ProviderSubjectErasureVendorAnswer {\n  /** The vendor erased what it held under the reference, in this call. */\n  ERASED = 'erased',\n  /**\n   * The vendor ACCEPTED the deletion and finishes it on its own schedule. Requires the call's `vendorCompletion`\n   * window: the erasure then reports COMPLETES_AT_VENDOR, by the instant the window lapses. Without a window the\n   * answer is treated as NOT_ERASED, because nothing bounds when the data leaves.\n   */\n  QUEUED = 'queued',\n  /** The vendor holds nothing under the reference. Every call answering this makes the effect NOTHING_TO_ERASE. */\n  NOTHING_HELD = 'nothing-held',\n  /** The vendor answered with a success status but reports it did not erase (a per-record failure inside a 2xx). */\n  NOT_ERASED = 'not-erased',\n}\n\n/**\n * The vendor's PUBLISHED schedule for finishing a deletion it accepted: an upper bound, in whole days, from the call.\n * Copied from the vendor's own documentation by the provider package, never computed from the answer.\n */\nexport interface ProviderSubjectErasureVendorCompletion {\n  /** At most this many days after the call, the vendor has finished the deletion. A positive integer. */\n  readonly withinDays: number;\n  /** Where the vendor publishes that schedule, so a reviewer can check the number against the source. */\n  readonly basis: string;\n}\n\n/** How one `execute` call reads the vendor's answer. */\nexport interface ProviderSubjectErasureCallOptions {\n  /**\n   * The call DELETES something, so a vendor answering 404 or 410 (the record is not there) means it is already erased:\n   * the step counts as done instead of failed. Set it only on a deletion: on a read, \"not found\" is not an erasure.\n   */\n  readonly absentMeansErased?: boolean;\n  /**\n   * The vendor finishes this deletion on its own schedule after accepting it, within this window. A successful answer\n   * is then QUEUED unless `readAnswer` says otherwise. A window that is not a positive whole number of days, or that\n   * names no basis, refuses the call before it is made.\n   */\n  readonly vendorCompletion?: ProviderSubjectErasureVendorCompletion;\n  /**\n   * Classify the vendor's successful answer (its parsed body). Absent: ERASED, or QUEUED when `vendorCompletion` is\n   * declared. A reader that throws, or returns anything outside {@link ProviderSubjectErasureVendorAnswer}, makes the\n   * call FAILED: an answer nobody could read is not evidence of an erasure.\n   */\n  readonly readAnswer?: (output: unknown) => ProviderSubjectErasureVendorAnswer;\n}\n\n/** What the engine hands a provider's erasure effect for one erasure. */\nexport interface ProviderSubjectErasureEffectInput {\n  /** The resource type of the subject being erased (`users` for an account holder). */\n  readonly subjectResourceType: string;\n  /**\n   * This vendor's identifiers for the subjects being erased: the values of the fields the operator declared\n   * under `providerComplianceChoices.<ref>.subjectReferences`, read before the local scrub. Unique, and never\n   * empty: when there is nothing to erase the engine reports NOTHING_TO_ERASE without calling `run`.\n   * Identifiers that come from a row under a legal hold, or from a subject the erasure kept under one, are left out.\n   */\n  readonly references: ReadonlyArray<string>;\n  /**\n   * Call one of THIS provider's operations on the application's connection, and get its answer. Never throws.\n   * Every call is a step of the erasure's outcome, labelled with `targetRef` (pass the reference the call is\n   * about), so the receipt says which identifier failed.\n   */\n  readonly execute: (\n    operationId: string,\n    input: Readonly<Record<string, unknown>>,\n    targetRef?: string,\n    options?: ProviderSubjectErasureCallOptions,\n  ) => Promise<ProviderSubjectErasureCallResult>;\n}\n\n/**\n * A provider's erasure effect: erase, at the vendor, what it keeps under each reference.\n *\n * Make it IDEMPOTENT: when every call fails (nothing applied), the engine runs it again, up to three times. Pass\n * `{ absentMeansErased: true }` on a deletion so a record the previous attempt already removed is not a failure.\n * It must finish within two minutes; past that the erasure stops waiting, refuses further calls, and reports from the\n * calls already recorded.\n *\n * Make one `execute` call per thing to erase, and keep going when one fails. Do not catch-and-ignore: the\n * outcome is derived from the calls, so a call you never made is a reference that stays at the vendor.\n * Declared on the backend provider module as `subjectErasureEffect`, beside a compliance profile whose\n * `subjectErasure.stance` is `EXTERNAL_ERASURE_OPERATION`; the engine refuses it on any other stance.\n */\nexport interface ProviderSubjectErasureEffect {\n  run(input: ProviderSubjectErasureEffectInput): Promise<void>;\n}\n/** @wildo_source:part:end external-connectors.models.subject-erasure-effect */\n"]}