@aglyn/plugins-outreach 1.0.0-beta.143

package/src/lib/model/outreach-api.d.ts

@@ -0,0 +1,210 @@
+/**
+ * @license
+ * Copyright 2026 Aglyn LLC
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *   http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+/**
+ * THE CONTRACT OF OUTREACH'S SETTINGS, SEQUENCE AND ENROLLMENT ROUTES
+ * (AGL-2980): what the console sends, what the routes answer, and every
+ * reason one refuses. Client-safe — types and the batch limit only.
+ *
+ * Every request names its organization (`orgId`, in the query of a `GET`
+ * and the JSON body of a `POST`): the routes serve an organization-level
+ * surface that names no site.
+ */
+import type { OutreachComposeError } from '../engine/compose';
+import type { OutreachComplianceIssue } from './compliance-settings';
+import type { OutreachAttestationKind, OutreachComplianceSettingsDocument, OutreachEnrollment, OutreachSequence } from './outreach.types';
+import type { OutreachSequenceDraft, OutreachSequenceIssue } from './sequence-draft';
+/** Every reason these routes refuse with, for a caller to branch on. */
+export type OutreachRouteRefusalReason = 'unauthenticated' | 'email-unverified' | 'org-required' | 'not-a-member' | 'not-org-wide' | 'permission' | 'entitlement' | 'method-not-allowed' | 'invalid-request' | 'invalid-settings' | 'invalid-sequence' | 'sequence-not-found' | 'sequence-archived' | 'sequence-not-active' | 'activation-refused' | 'delete-refused' | 'mailbox-unavailable' | 'enrollment-not-found' | 'transition-refused' | 'view-not-found' | 'view-unsupported' | 'contact-not-found';
+/** A refusal, in the one shape every route answers with. */
+export interface OutreachRouteRefusal {
+    /** A sentence written for the person reading it. */
+    error: string;
+    reason: OutreachRouteRefusalReason;
+    /** The field-level reasons behind an `invalid-*` or `activation-refused` refusal. */
+    issues?: ReadonlyArray<OutreachComplianceIssue | OutreachSequenceIssue>;
+}
+/** `GET outreach/settings?orgId` — and the answer to a save. */
+export interface OutreachSettingsResponse {
+    ok: true;
+    settings: OutreachComplianceSettingsDocument;
+}
+/** `POST outreach/settings` */
+export interface OutreachSettingsSaveRequest {
+    orgId: string;
+    legalName: string;
+    brandName: string;
+    postalAddress: string;
+    allowedCountries: string[];
+}
+/** The answer to a save: the settings as stored, and whether anything changed. */
+export interface OutreachSettingsSaveResponse extends OutreachSettingsResponse {
+    changed: boolean;
+}
+/** `POST outreach/sequences/save` — a new sequence without `sequenceId`, an edit with one. */
+export interface OutreachSequenceSaveRequest {
+    orgId: string;
+    sequenceId?: string;
+    sequence: OutreachSequenceDraft;
+}
+export interface OutreachSequenceSaveResponse {
+    ok: true;
+    sequence: OutreachSequence;
+    created: boolean;
+    /** What the save allowed but probably isn't what was meant. */
+    warnings: OutreachSequenceIssue[];
+}
+/** What `outreach/sequences/status` does to a sequence. */
+export type OutreachSequenceAction = 'activate' | 'pause' | 'archive';
+/** `POST outreach/sequences/status` */
+export interface OutreachSequenceStatusRequest {
+    orgId: string;
+    sequenceId: string;
+    action: OutreachSequenceAction;
+}
+export interface OutreachSequenceStatusResponse {
+    ok: true;
+    sequence: OutreachSequence;
+    /** The open enrollments an archive stopped; `0` for anything else. */
+    stoppedEnrollments: number;
+}
+/** `POST outreach/sequences/delete` — a draft nobody was ever enrolled in. */
+export interface OutreachSequenceDeleteRequest {
+    orgId: string;
+    sequenceId: string;
+}
+/** The most people one preview or one enroll reads. */
+export declare const OUTREACH_ENROLL_BATCH_MAX = 50;
+/** Where the people to enroll come from: a saved Contacts view, or contacts picked by search. */
+export type OutreachEnrollSource = {
+    kind: 'view';
+    viewId: string;
+} | {
+    kind: 'contacts';
+    contactIds: string[];
+};
+/** `POST outreach/enroll/preview` */
+export interface OutreachEnrollPreviewRequest {
+    orgId: string;
+    sequenceId: string;
+    source: OutreachEnrollSource;
+}
+/**
+ * Where one person stands:
+ *
+ * - `eligible` — enrolled on Confirm as they are;
+ * - `needs_confirmation` — enrolled once the rep writes the personal line
+ *   and ticks the attestations `requires` names;
+ * - `blocked` — refused whatever the rep confirms, for the `blocks` given.
+ */
+export type OutreachEnrollPreviewStatus = 'eligible' | 'needs_confirmation' | 'blocked';
+/** One reason a person can't be enrolled, in a sentence a rep can act on. */
+export interface OutreachEnrollBlock {
+    code: string;
+    reason: string;
+}
+export interface OutreachEnrollPreviewPerson {
+    contactId: string;
+    name: string;
+    /** The address the steps would go to, or `null` when the contact has none. */
+    email: string | null;
+    /** No inbound capture behind them — the heavier rules apply. */
+    cold: boolean;
+    /** ISO-3166-1 alpha-2, when anything names one. */
+    country: string | null;
+    status: OutreachEnrollPreviewStatus;
+    /** Why a `blocked` person is refused; empty otherwise. */
+    blocks: OutreachEnrollBlock[];
+    /** What the rep must supply before a `needs_confirmation` person is enrolled. */
+    requires: {
+        personalLine: boolean;
+        attestations: OutreachAttestationKind[];
+    };
+}
+export interface OutreachEnrollPreviewResponse {
+    ok: true;
+    people: OutreachEnrollPreviewPerson[];
+    /** Everyone the source named, before the batch limit. */
+    total: number;
+    /** True when the source named more people than one enrollment reads. */
+    truncated: boolean;
+}
+/** One person to enroll, with what the rep supplied for them. */
+export interface OutreachEnrollPersonRequest {
+    contactId: string;
+    personalLine?: string;
+    attestations?: OutreachAttestationKind[];
+}
+/** `POST outreach/enroll` — the gates are checked again, here, before anything is written. */
+export interface OutreachEnrollRequest {
+    orgId: string;
+    sequenceId: string;
+    people: OutreachEnrollPersonRequest[];
+}
+export type OutreachEnrollOutcome = {
+    contactId: string;
+    email: string | null;
+    outcome: 'enrolled';
+    enrollmentId: string;
+} | {
+    contactId: string;
+    email: string | null;
+    outcome: 'blocked';
+    blocks: OutreachEnrollBlock[];
+};
+export interface OutreachEnrollResponse {
+    ok: true;
+    results: OutreachEnrollOutcome[];
+    enrolled: number;
+}
+/** What a member may do to one enrollment. */
+export type OutreachEnrollmentAction = 'pause' | 'resume' | 'stop' | 'do_not_contact';
+/** `POST outreach/enrollments/action` */
+export interface OutreachEnrollmentActionRequest {
+    orgId: string;
+    enrollmentId: string;
+    action: OutreachEnrollmentAction;
+    /** Why, for a stop or a do-not-contact. */
+    detail?: string;
+}
+export interface OutreachEnrollmentActionResponse {
+    ok: true;
+    /** False when the enrollment was already where the action would put it. */
+    changed: boolean;
+    enrollment: OutreachEnrollment;
+    /** Other open enrollments of the same address a do-not-contact stopped. */
+    stoppedOthers: number;
+}
+/** `POST outreach/preview` — one email of a saved sequence, as a person would get it. */
+export interface OutreachPreviewRequest {
+    orgId: string;
+    sequenceId: string;
+    /** The contact to write it to; a sample person when absent. */
+    contactId?: string;
+    personalLine?: string;
+    /** Which step; the first email when absent. */
+    stepIndex?: number;
+}
+export interface OutreachPreviewResponse {
+    ok: true;
+    stepIndex: number;
+    subject: string;
+    /** The plain text, footer included. */
+    text: string;
+    unresolvedFields: string[];
+    /** Why it could not be written, when it could not. */
+    error: OutreachComposeError | null;
+}

package/src/lib/model/outreach-api.js

@@ -0,0 +1,28 @@
+/**
+ * @license
+ * Copyright 2026 Aglyn LLC
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *   http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */ /**
+ * THE CONTRACT OF OUTREACH'S SETTINGS, SEQUENCE AND ENROLLMENT ROUTES
+ * (AGL-2980): what the console sends, what the routes answer, and every
+ * reason one refuses. Client-safe — types and the batch limit only.
+ *
+ * Every request names its organization (`orgId`, in the query of a `GET`
+ * and the JSON body of a `POST`): the routes serve an organization-level
+ * surface that names no site.
+ */ /*==========================================
+ * ENROLLING
+ *==========================================*/ /** The most people one preview or one enroll reads. */ export const OUTREACH_ENROLL_BATCH_MAX = 50;
+
+//# sourceMappingURL=outreach-api.js.map

package/src/lib/model/outreach-api.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../../../../../../libs/plugins/outreach/src/lib/model/outreach-api.ts"],"sourcesContent":["/**\n * @license\n * Copyright 2026 Aglyn LLC\n *\n * Licensed under the Apache License, Version 2.0 (the \"License\");\n * you may not use this file except in compliance with the License.\n * You may obtain a copy of the License at\n *\n *   http://www.apache.org/licenses/LICENSE-2.0\n *\n * Unless required by applicable law or agreed to in writing, software\n * distributed under the License is distributed on an \"AS IS\" BASIS,\n * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n * See the License for the specific language governing permissions and\n * limitations under the License.\n */\n\n/**\n * THE CONTRACT OF OUTREACH'S SETTINGS, SEQUENCE AND ENROLLMENT ROUTES\n * (AGL-2980): what the console sends, what the routes answer, and every\n * reason one refuses. Client-safe — types and the batch limit only.\n *\n * Every request names its organization (`orgId`, in the query of a `GET`\n * and the JSON body of a `POST`): the routes serve an organization-level\n * surface that names no site.\n */\n\nimport type { OutreachComposeError } from '../engine/compose'\nimport type { OutreachComplianceIssue } from './compliance-settings'\nimport type {\n  OutreachAttestationKind,\n  OutreachComplianceSettingsDocument,\n  OutreachEnrollment,\n  OutreachSequence,\n} from './outreach.types'\nimport type { OutreachSequenceDraft, OutreachSequenceIssue } from './sequence-draft'\n\n/** Every reason these routes refuse with, for a caller to branch on. */\nexport type OutreachRouteRefusalReason =\n  | 'unauthenticated'\n  | 'email-unverified'\n  | 'org-required'\n  | 'not-a-member'\n  | 'not-org-wide'\n  | 'permission'\n  | 'entitlement'\n  | 'method-not-allowed'\n  | 'invalid-request'\n  | 'invalid-settings'\n  | 'invalid-sequence'\n  | 'sequence-not-found'\n  | 'sequence-archived'\n  | 'sequence-not-active'\n  | 'activation-refused'\n  | 'delete-refused'\n  | 'mailbox-unavailable'\n  | 'enrollment-not-found'\n  | 'transition-refused'\n  | 'view-not-found'\n  | 'view-unsupported'\n  | 'contact-not-found'\n\n/** A refusal, in the one shape every route answers with. */\nexport interface OutreachRouteRefusal {\n  /** A sentence written for the person reading it. */\n  error: string\n  reason: OutreachRouteRefusalReason\n  /** The field-level reasons behind an `invalid-*` or `activation-refused` refusal. */\n  issues?: ReadonlyArray<OutreachComplianceIssue | OutreachSequenceIssue>\n}\n\n/*==========================================\n * COMPLIANCE SETTINGS\n *==========================================*/\n\n/** `GET outreach/settings?orgId` — and the answer to a save. */\nexport interface OutreachSettingsResponse {\n  ok: true\n  settings: OutreachComplianceSettingsDocument\n}\n\n/** `POST outreach/settings` */\nexport interface OutreachSettingsSaveRequest {\n  orgId: string\n  legalName: string\n  brandName: string\n  postalAddress: string\n  allowedCountries: string[]\n}\n\n/** The answer to a save: the settings as stored, and whether anything changed. */\nexport interface OutreachSettingsSaveResponse extends OutreachSettingsResponse {\n  changed: boolean\n}\n\n/*==========================================\n * SEQUENCES\n *==========================================*/\n\n/** `POST outreach/sequences/save` — a new sequence without `sequenceId`, an edit with one. */\nexport interface OutreachSequenceSaveRequest {\n  orgId: string\n  sequenceId?: string\n  sequence: OutreachSequenceDraft\n}\n\nexport interface OutreachSequenceSaveResponse {\n  ok: true\n  sequence: OutreachSequence\n  created: boolean\n  /** What the save allowed but probably isn't what was meant. */\n  warnings: OutreachSequenceIssue[]\n}\n\n/** What `outreach/sequences/status` does to a sequence. */\nexport type OutreachSequenceAction = 'activate' | 'pause' | 'archive'\n\n/** `POST outreach/sequences/status` */\nexport interface OutreachSequenceStatusRequest {\n  orgId: string\n  sequenceId: string\n  action: OutreachSequenceAction\n}\n\nexport interface OutreachSequenceStatusResponse {\n  ok: true\n  sequence: OutreachSequence\n  /** The open enrollments an archive stopped; `0` for anything else. */\n  stoppedEnrollments: number\n}\n\n/** `POST outreach/sequences/delete` — a draft nobody was ever enrolled in. */\nexport interface OutreachSequenceDeleteRequest {\n  orgId: string\n  sequenceId: string\n}\n\n/*==========================================\n * ENROLLING\n *==========================================*/\n\n/** The most people one preview or one enroll reads. */\nexport const OUTREACH_ENROLL_BATCH_MAX = 50\n\n/** Where the people to enroll come from: a saved Contacts view, or contacts picked by search. */\nexport type OutreachEnrollSource =\n  | { kind: 'view'; viewId: string }\n  | { kind: 'contacts'; contactIds: string[] }\n\n/** `POST outreach/enroll/preview` */\nexport interface OutreachEnrollPreviewRequest {\n  orgId: string\n  sequenceId: string\n  source: OutreachEnrollSource\n}\n\n/**\n * Where one person stands:\n *\n * - `eligible` — enrolled on Confirm as they are;\n * - `needs_confirmation` — enrolled once the rep writes the personal line\n *   and ticks the attestations `requires` names;\n * - `blocked` — refused whatever the rep confirms, for the `blocks` given.\n */\nexport type OutreachEnrollPreviewStatus = 'eligible' | 'needs_confirmation' | 'blocked'\n\n/** One reason a person can't be enrolled, in a sentence a rep can act on. */\nexport interface OutreachEnrollBlock {\n  code: string\n  reason: string\n}\n\nexport interface OutreachEnrollPreviewPerson {\n  contactId: string\n  name: string\n  /** The address the steps would go to, or `null` when the contact has none. */\n  email: string | null\n  /** No inbound capture behind them — the heavier rules apply. */\n  cold: boolean\n  /** ISO-3166-1 alpha-2, when anything names one. */\n  country: string | null\n  status: OutreachEnrollPreviewStatus\n  /** Why a `blocked` person is refused; empty otherwise. */\n  blocks: OutreachEnrollBlock[]\n  /** What the rep must supply before a `needs_confirmation` person is enrolled. */\n  requires: {\n    personalLine: boolean\n    attestations: OutreachAttestationKind[]\n  }\n}\n\nexport interface OutreachEnrollPreviewResponse {\n  ok: true\n  people: OutreachEnrollPreviewPerson[]\n  /** Everyone the source named, before the batch limit. */\n  total: number\n  /** True when the source named more people than one enrollment reads. */\n  truncated: boolean\n}\n\n/** One person to enroll, with what the rep supplied for them. */\nexport interface OutreachEnrollPersonRequest {\n  contactId: string\n  personalLine?: string\n  attestations?: OutreachAttestationKind[]\n}\n\n/** `POST outreach/enroll` — the gates are checked again, here, before anything is written. */\nexport interface OutreachEnrollRequest {\n  orgId: string\n  sequenceId: string\n  people: OutreachEnrollPersonRequest[]\n}\n\nexport type OutreachEnrollOutcome =\n  | { contactId: string; email: string | null; outcome: 'enrolled'; enrollmentId: string }\n  | { contactId: string; email: string | null; outcome: 'blocked'; blocks: OutreachEnrollBlock[] }\n\nexport interface OutreachEnrollResponse {\n  ok: true\n  results: OutreachEnrollOutcome[]\n  enrolled: number\n}\n\n/*==========================================\n * ENROLLMENTS\n *==========================================*/\n\n/** What a member may do to one enrollment. */\nexport type OutreachEnrollmentAction = 'pause' | 'resume' | 'stop' | 'do_not_contact'\n\n/** `POST outreach/enrollments/action` */\nexport interface OutreachEnrollmentActionRequest {\n  orgId: string\n  enrollmentId: string\n  action: OutreachEnrollmentAction\n  /** Why, for a stop or a do-not-contact. */\n  detail?: string\n}\n\nexport interface OutreachEnrollmentActionResponse {\n  ok: true\n  /** False when the enrollment was already where the action would put it. */\n  changed: boolean\n  enrollment: OutreachEnrollment\n  /** Other open enrollments of the same address a do-not-contact stopped. */\n  stoppedOthers: number\n}\n\n/*==========================================\n * PREVIEW\n *==========================================*/\n\n/** `POST outreach/preview` — one email of a saved sequence, as a person would get it. */\nexport interface OutreachPreviewRequest {\n  orgId: string\n  sequenceId: string\n  /** The contact to write it to; a sample person when absent. */\n  contactId?: string\n  personalLine?: string\n  /** Which step; the first email when absent. */\n  stepIndex?: number\n}\n\nexport interface OutreachPreviewResponse {\n  ok: true\n  stepIndex: number\n  subject: string\n  /** The plain text, footer included. */\n  text: string\n  unresolvedFields: string[]\n  /** Why it could not be written, when it could not. */\n  error: OutreachComposeError | null\n}\n"],"names":["OUTREACH_ENROLL_BATCH_MAX"],"mappings":"AAAA;;;;;;;;;;;;;;;CAeC,GAED;;;;;;;;CAQC,GAgHD;;4CAE4C,GAE5C,qDAAqD,GACrD,OAAO,MAAMA,4BAA4B,GAAE"}