@aglyn/plugins-outreach 1.0.0-beta.143

package/src/lib/routes/route-gate.js

@@ -0,0 +1,87 @@
+/**
+ * @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.
+ */ import { checkEntitlement } from "@aglyn/aglyn/server";
+import { isEmailVerified, isImpersonationSession } from "@aglyn/tenant-data-admin/server/firebase-admin";
+import { invalidIdTokenResponse } from "@aglyn/tenant-data-admin/server/id-token-refusal";
+import { OUTREACH_USE_PERMISSION } from "../constants/bundle-common.js";
+import { outreachRefusal, readOutreachDocumentId } from "./route-http.js";
+function bearer(request) {
+    var _request_headers_get;
+    const authorization = (_request_headers_get = request.headers.get('authorization')) != null ? _request_headers_get : '';
+    return authorization.startsWith('Bearer ') ? authorization.slice('Bearer '.length) : null;
+}
+export async function outreachRouteGate(request, rawOrgId, deps, extra = []) {
+    var _ref;
+    const token = bearer(request);
+    if (!token) return outreachRefusal(401, 'unauthenticated', 'Sign in to use Sequences.');
+    let decoded;
+    try {
+        decoded = await deps.verifyIdToken(token);
+    } catch (error) {
+        // A refused credential is the caller's; an Auth outage is ours and
+        // propagates, so it answers 500 instead of "sign in again".
+        if (invalidIdTokenResponse(error)) {
+            return outreachRefusal(401, 'unauthenticated', 'Your sign-in could not be confirmed. Sign in again.');
+        }
+        throw error;
+    }
+    if (!isEmailVerified(decoded) && !isImpersonationSession(decoded)) {
+        return outreachRefusal(403, 'email-unverified', 'Verify your email address before using Sequences.');
+    }
+    const orgId = readOutreachDocumentId(rawOrgId);
+    if (!orgId) return outreachRefusal(400, 'org-required', 'Open an organization before using Sequences.');
+    const membership = await deps.resolveOrgPermissions(decoded.uid, {
+        orgId
+    });
+    // A targeted org the account is not on answers with that org's id and no
+    // role — as does a lookup that failed closed — so the role is the test.
+    if (!membership.role || membership.orgId !== orgId) {
+        return outreachRefusal(403, 'not-a-member', 'You are not a member of that organization.');
+    }
+    if (!membership.orgWide) {
+        return outreachRefusal(403, 'not-org-wide', 'Sequences covers the whole organization, and your access is to particular sites.');
+    }
+    if (membership.permissions[OUTREACH_USE_PERMISSION] !== true) {
+        return outreachRefusal(403, 'permission', 'Your role does not include Use Sequences.');
+    }
+    for (const permission of extra){
+        if (!await deps.holdsOrgCatalogPermission(decoded.uid, orgId, permission.key)) {
+            return outreachRefusal(403, 'permission', permission.refusal);
+        }
+    }
+    const org = (_ref = await deps.readOrg(orgId)) != null ? _ref : {};
+    if (!checkEntitlement(org, 'outreach')) {
+        return outreachRefusal(403, 'entitlement', "Sequences isn't available to this workspace yet.");
+    }
+    const staff = decoded['staff'] === true;
+    const locked = await deps.lockdownRefusal({
+        request,
+        staff,
+        uid: decoded.uid,
+        org
+    });
+    if (locked) return locked;
+    return {
+        uid: decoded.uid,
+        email: typeof decoded.email === 'string' ? decoded.email.trim().toLowerCase() : null,
+        staff,
+        orgId,
+        org,
+        isOrgAdmin: membership.isOwner
+    };
+}
+
+//# sourceMappingURL=route-gate.js.map

package/src/lib/routes/route-gate.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../../../../../../libs/plugins/outreach/src/lib/routes/route-gate.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\nimport { checkEntitlement } from '@aglyn/aglyn/server'\nimport {\n  isEmailVerified,\n  isImpersonationSession,\n} from '@aglyn/tenant-data-admin/server/firebase-admin'\nimport { invalidIdTokenResponse } from '@aglyn/tenant-data-admin/server/id-token-refusal'\nimport type { DecodedIdToken } from 'firebase-admin/auth'\nimport { OUTREACH_USE_PERMISSION } from '../constants/bundle-common'\nimport { outreachRefusal, readOutreachDocumentId } from './route-http'\n\n/**\n * THE GATE EVERY SETTINGS, SEQUENCE AND ENROLLMENT ROUTE CLIMBS (AGL-2980).\n *\n * The console dispatcher has already refused a request while\n * `release_outreach` is off for it, an unverified account's token, a\n * lockdown with no org in scope, and a caller over the console rate limit —\n * every route here is registered under the `outreach/` prefix, which is what\n * puts it behind those. What the dispatcher cannot know is anything about\n * the member, so each rung below is this plugin's:\n *\n *   401  no bearer token, or one the verifier refused\n *   403  the account's address is unverified (an impersonation session is exempt)\n *   400  the request did not name an organization\n *   403  not a member of it, a site collaborator without org-wide reach, or\n *        without `outreach.use` — or without a permission the route adds\n *   403  the organization does not hold the `outreach` entitlement\n *   423  lockdown, now with the organization and the account in scope\n *\n * The reach is org-wide for the reason the rules give: a sequence enrolls\n * people from every site of the organization, so none of it is a fact\n * about the one site a collaborator was invited to.\n *\n * `resolveOrgPermissions` is always given the concrete org id. Called\n * without one it resolves a caller with no org at all as that future org's\n * owner, which is right for a fresh signup and wrong for every question\n * asked here.\n */\n\nexport interface OutreachRouteGateDeps {\n  verifyIdToken(idToken: string): Promise<DecodedIdToken>\n  resolveOrgPermissions(\n    uid: string,\n    context: { orgId: string },\n  ): Promise<{\n    orgId: string | null\n    /** `null` when the account is not on the organization's roster. */\n    role: string | null\n    isOwner: boolean\n    orgWide: boolean\n    permissions: Partial<Record<string, boolean | undefined>>\n  }>\n  /**\n   * Whether the member holds a CATALOG permission (`data.manage`) as the\n   * org's roles resolve it. Asked separately because the map\n   * `resolveOrgPermissions` answers carries the legacy keys and the plugins'\n   * own, never a catalog key: read there, a catalog key refuses everyone.\n   */\n  holdsOrgCatalogPermission(uid: string, orgId: string, key: string): Promise<boolean>\n  readOrg(orgId: string): Promise<Record<string, unknown> | null>\n  lockdownRefusal(options: {\n    request: Request\n    staff: boolean\n    uid: string\n    org: Record<string, unknown>\n  }): Promise<Response | null>\n}\n\n/** Who is asking, once the gate let them through. */\nexport interface OutreachRouteCaller {\n  uid: string\n  /** The account's sign-in address, lower-cased, when the token carries one. */\n  email: string | null\n  staff: boolean\n  orgId: string\n  /** The organization document the entitlement was read from. */\n  org: Record<string, unknown>\n  /** An owner or admin of the organization, who may send from any member's mailbox. */\n  isOrgAdmin: boolean\n}\n\n/**\n * A catalog permission a route asks for beyond `outreach.use`, with its\n * refusal — `data.manage` for a route that reads the CRM's people, which\n * the contacts' own rules gate on.\n */\nexport interface OutreachRouteExtraPermission {\n  key: string\n  /** Why the route needs it, as the refusal says it. */\n  refusal: string\n}\n\nfunction bearer(request: Request): string | null {\n  const authorization = request.headers.get('authorization') ?? ''\n  return authorization.startsWith('Bearer ') ? authorization.slice('Bearer '.length) : null\n}\n\nexport async function outreachRouteGate(\n  request: Request,\n  rawOrgId: unknown,\n  deps: OutreachRouteGateDeps,\n  extra: readonly OutreachRouteExtraPermission[] = [],\n): Promise<Response | OutreachRouteCaller> {\n  const token = bearer(request)\n  if (!token) return outreachRefusal(401, 'unauthenticated', 'Sign in to use Sequences.')\n  let decoded: DecodedIdToken\n  try {\n    decoded = await deps.verifyIdToken(token)\n  } catch (error) {\n    // A refused credential is the caller's; an Auth outage is ours and\n    // propagates, so it answers 500 instead of \"sign in again\".\n    if (invalidIdTokenResponse(error)) {\n      return outreachRefusal(401, 'unauthenticated', 'Your sign-in could not be confirmed. Sign in again.')\n    }\n    throw error\n  }\n  if (!isEmailVerified(decoded) && !isImpersonationSession(decoded)) {\n    return outreachRefusal(403, 'email-unverified', 'Verify your email address before using Sequences.')\n  }\n\n  const orgId = readOutreachDocumentId(rawOrgId)\n  if (!orgId) return outreachRefusal(400, 'org-required', 'Open an organization before using Sequences.')\n\n  const membership = await deps.resolveOrgPermissions(decoded.uid, { orgId })\n  // A targeted org the account is not on answers with that org's id and no\n  // role — as does a lookup that failed closed — so the role is the test.\n  if (!membership.role || membership.orgId !== orgId) {\n    return outreachRefusal(403, 'not-a-member', 'You are not a member of that organization.')\n  }\n  if (!membership.orgWide) {\n    return outreachRefusal(\n      403,\n      'not-org-wide',\n      'Sequences covers the whole organization, and your access is to particular sites.',\n    )\n  }\n  if (membership.permissions[OUTREACH_USE_PERMISSION] !== true) {\n    return outreachRefusal(403, 'permission', 'Your role does not include Use Sequences.')\n  }\n  for (const permission of extra) {\n    if (!(await deps.holdsOrgCatalogPermission(decoded.uid, orgId, permission.key))) {\n      return outreachRefusal(403, 'permission', permission.refusal)\n    }\n  }\n\n  const org = (await deps.readOrg(orgId)) ?? {}\n  if (!checkEntitlement(org, 'outreach')) {\n    return outreachRefusal(403, 'entitlement', \"Sequences isn't available to this workspace yet.\")\n  }\n  const staff = decoded['staff'] === true\n  const locked = await deps.lockdownRefusal({ request, staff, uid: decoded.uid, org })\n  if (locked) return locked\n\n  return {\n    uid: decoded.uid,\n    email: typeof decoded.email === 'string' ? decoded.email.trim().toLowerCase() : null,\n    staff,\n    orgId,\n    org,\n    isOrgAdmin: membership.isOwner,\n  }\n}\n"],"names":["checkEntitlement","isEmailVerified","isImpersonationSession","invalidIdTokenResponse","OUTREACH_USE_PERMISSION","outreachRefusal","readOutreachDocumentId","bearer","request","authorization","headers","get","startsWith","slice","length","outreachRouteGate","rawOrgId","deps","extra","token","decoded","verifyIdToken","error","orgId","membership","resolveOrgPermissions","uid","role","orgWide","permissions","permission","holdsOrgCatalogPermission","key","refusal","org","readOrg","staff","locked","lockdownRefusal","email","trim","toLowerCase","isOrgAdmin","isOwner"],"mappings":"AAAA;;;;;;;;;;;;;;;CAeC,GAED,SAASA,gBAAgB,QAAQ,sBAAqB;AACtD,SACEC,eAAe,EACfC,sBAAsB,QACjB,iDAAgD;AACvD,SAASC,sBAAsB,QAAQ,mDAAkD;AAEzF,SAASC,uBAAuB,QAAQ,gCAA4B;AACpE,SAASC,eAAe,EAAEC,sBAAsB,QAAQ,kBAAc;AAmFtE,SAASC,OAAOC,OAAgB;QACRA;IAAtB,MAAMC,iBAAgBD,uBAAAA,QAAQE,OAAO,CAACC,GAAG,CAAC,4BAApBH,uBAAwC;IAC9D,OAAOC,cAAcG,UAAU,CAAC,aAAaH,cAAcI,KAAK,CAAC,UAAUC,MAAM,IAAI;AACvF;AAEA,OAAO,eAAeC,kBACpBP,OAAgB,EAChBQ,QAAiB,EACjBC,IAA2B,EAC3BC,QAAiD,EAAE;QA4CtC;IA1Cb,MAAMC,QAAQZ,OAAOC;IACrB,IAAI,CAACW,OAAO,OAAOd,gBAAgB,KAAK,mBAAmB;IAC3D,IAAIe;IACJ,IAAI;QACFA,UAAU,MAAMH,KAAKI,aAAa,CAACF;IACrC,EAAE,OAAOG,OAAO;QACd,mEAAmE;QACnE,4DAA4D;QAC5D,IAAInB,uBAAuBmB,QAAQ;YACjC,OAAOjB,gBAAgB,KAAK,mBAAmB;QACjD;QACA,MAAMiB;IACR;IACA,IAAI,CAACrB,gBAAgBmB,YAAY,CAAClB,uBAAuBkB,UAAU;QACjE,OAAOf,gBAAgB,KAAK,oBAAoB;IAClD;IAEA,MAAMkB,QAAQjB,uBAAuBU;IACrC,IAAI,CAACO,OAAO,OAAOlB,gBAAgB,KAAK,gBAAgB;IAExD,MAAMmB,aAAa,MAAMP,KAAKQ,qBAAqB,CAACL,QAAQM,GAAG,EAAE;QAAEH;IAAM;IACzE,yEAAyE;IACzE,wEAAwE;IACxE,IAAI,CAACC,WAAWG,IAAI,IAAIH,WAAWD,KAAK,KAAKA,OAAO;QAClD,OAAOlB,gBAAgB,KAAK,gBAAgB;IAC9C;IACA,IAAI,CAACmB,WAAWI,OAAO,EAAE;QACvB,OAAOvB,gBACL,KACA,gBACA;IAEJ;IACA,IAAImB,WAAWK,WAAW,CAACzB,wBAAwB,KAAK,MAAM;QAC5D,OAAOC,gBAAgB,KAAK,cAAc;IAC5C;IACA,KAAK,MAAMyB,cAAcZ,MAAO;QAC9B,IAAI,CAAE,MAAMD,KAAKc,yBAAyB,CAACX,QAAQM,GAAG,EAAEH,OAAOO,WAAWE,GAAG,GAAI;YAC/E,OAAO3B,gBAAgB,KAAK,cAAcyB,WAAWG,OAAO;QAC9D;IACF;IAEA,MAAMC,OAAO,OAAA,MAAMjB,KAAKkB,OAAO,CAACZ,kBAAnB,OAA8B,CAAC;IAC5C,IAAI,CAACvB,iBAAiBkC,KAAK,aAAa;QACtC,OAAO7B,gBAAgB,KAAK,eAAe;IAC7C;IACA,MAAM+B,QAAQhB,OAAO,CAAC,QAAQ,KAAK;IACnC,MAAMiB,SAAS,MAAMpB,KAAKqB,eAAe,CAAC;QAAE9B;QAAS4B;QAAOV,KAAKN,QAAQM,GAAG;QAAEQ;IAAI;IAClF,IAAIG,QAAQ,OAAOA;IAEnB,OAAO;QACLX,KAAKN,QAAQM,GAAG;QAChBa,OAAO,OAAOnB,QAAQmB,KAAK,KAAK,WAAWnB,QAAQmB,KAAK,CAACC,IAAI,GAAGC,WAAW,KAAK;QAChFL;QACAb;QACAW;QACAQ,YAAYlB,WAAWmB,OAAO;IAChC;AACF"}

package/src/lib/routes/route-http.d.ts

@@ -0,0 +1,32 @@
+/**
+ * @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 few shapes every settings, sequence and enrollment route answers in
+ * (AGL-2980): a `200` with a body, a refusal with a sentence and a stable
+ * reason, and a JSON body read without trusting it. Nothing is cached — an
+ * answer about a workspace's sending is stale the moment it is written.
+ */
+import type { OutreachRouteRefusal, OutreachRouteRefusalReason } from '../model/outreach-api';
+/** A `200` carrying `body`. */
+export declare function outreachOk(body: unknown): Response;
+/** A refusal in the one shape the routes answer with. */
+export declare function outreachRefusal(status: number, reason: OutreachRouteRefusalReason, error: string, extra?: Omit<OutreachRouteRefusal, 'error' | 'reason'>): Response;
+export declare function outreachMethodNotAllowed(allow: string): Response;
+/** The request's JSON object, or `{}` for a body that is not one. */
+export declare function readOutreachJsonBody(request: Request): Promise<Record<string, unknown>>;
+/** `value` when it is a plain document id, else `null`. */
+export declare function readOutreachDocumentId(value: unknown): string | null;

package/src/lib/routes/route-http.js

@@ -0,0 +1,62 @@
+/**
+ * @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 few shapes every settings, sequence and enrollment route answers in
+ * (AGL-2980): a `200` with a body, a refusal with a sentence and a stable
+ * reason, and a JSON body read without trusting it. Nothing is cached — an
+ * answer about a workspace's sending is stale the moment it is written.
+ */ import { _ as _extends } from "@swc/helpers/_/_extends";
+const NO_STORE = {
+    'Cache-Control': 'no-store'
+};
+/** A `200` carrying `body`. */ export function outreachOk(body) {
+    return Response.json(body, {
+        status: 200,
+        headers: NO_STORE
+    });
+}
+/** A refusal in the one shape the routes answer with. */ export function outreachRefusal(status, reason, error, extra) {
+    const body = _extends({
+        error,
+        reason
+    }, extra != null ? extra : {});
+    return Response.json(body, {
+        status,
+        headers: NO_STORE
+    });
+}
+export function outreachMethodNotAllowed(allow) {
+    return Response.json({
+        error: 'Method not allowed',
+        reason: 'method-not-allowed'
+    }, {
+        status: 405,
+        headers: _extends({}, NO_STORE, {
+            Allow: allow
+        })
+    });
+}
+/** The request's JSON object, or `{}` for a body that is not one. */ export async function readOutreachJsonBody(request) {
+    const body = await request.json().catch(()=>null);
+    return body && typeof body === 'object' && !Array.isArray(body) ? body : {};
+}
+/** A document id as a request may name one: a plain path segment. */ const DOCUMENT_ID = /^[A-Za-z0-9_-]{1,128}$/;
+/** `value` when it is a plain document id, else `null`. */ export function readOutreachDocumentId(value) {
+    const id = typeof value === 'string' ? value.trim() : '';
+    return DOCUMENT_ID.test(id) ? id : null;
+}
+
+//# sourceMappingURL=route-http.js.map

package/src/lib/routes/route-http.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../../../../../../libs/plugins/outreach/src/lib/routes/route-http.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 few shapes every settings, sequence and enrollment route answers in\n * (AGL-2980): a `200` with a body, a refusal with a sentence and a stable\n * reason, and a JSON body read without trusting it. Nothing is cached — an\n * answer about a workspace's sending is stale the moment it is written.\n */\n\nimport type {\n  OutreachRouteRefusal,\n  OutreachRouteRefusalReason,\n} from '../model/outreach-api'\n\nconst NO_STORE = { 'Cache-Control': 'no-store' }\n\n/** A `200` carrying `body`. */\nexport function outreachOk(body: unknown): Response {\n  return Response.json(body, { status: 200, headers: NO_STORE })\n}\n\n/** A refusal in the one shape the routes answer with. */\nexport function outreachRefusal(\n  status: number,\n  reason: OutreachRouteRefusalReason,\n  error: string,\n  extra?: Omit<OutreachRouteRefusal, 'error' | 'reason'>,\n): Response {\n  const body: OutreachRouteRefusal = { error, reason, ...(extra ?? {}) }\n  return Response.json(body, { status, headers: NO_STORE })\n}\n\nexport function outreachMethodNotAllowed(allow: string): Response {\n  return Response.json(\n    { error: 'Method not allowed', reason: 'method-not-allowed' } satisfies OutreachRouteRefusal,\n    { status: 405, headers: { ...NO_STORE, Allow: allow } },\n  )\n}\n\n/** The request's JSON object, or `{}` for a body that is not one. */\nexport async function readOutreachJsonBody(request: Request): Promise<Record<string, unknown>> {\n  const body = await request.json().catch(() => null)\n  return body && typeof body === 'object' && !Array.isArray(body)\n    ? (body as Record<string, unknown>)\n    : {}\n}\n\n/** A document id as a request may name one: a plain path segment. */\nconst DOCUMENT_ID = /^[A-Za-z0-9_-]{1,128}$/\n\n/** `value` when it is a plain document id, else `null`. */\nexport function readOutreachDocumentId(value: unknown): string | null {\n  const id = typeof value === 'string' ? value.trim() : ''\n  return DOCUMENT_ID.test(id) ? id : null\n}\n"],"names":["NO_STORE","outreachOk","body","Response","json","status","headers","outreachRefusal","reason","error","extra","outreachMethodNotAllowed","allow","Allow","readOutreachJsonBody","request","catch","Array","isArray","DOCUMENT_ID","readOutreachDocumentId","value","id","trim","test"],"mappings":"AAAA;;;;;;;;;;;;;;;CAeC,GAED;;;;;CAKC;AAOD,MAAMA,WAAW;IAAE,iBAAiB;AAAW;AAE/C,6BAA6B,GAC7B,OAAO,SAASC,WAAWC,IAAa;IACtC,OAAOC,SAASC,IAAI,CAACF,MAAM;QAAEG,QAAQ;QAAKC,SAASN;IAAS;AAC9D;AAEA,uDAAuD,GACvD,OAAO,SAASO,gBACdF,MAAc,EACdG,MAAkC,EAClCC,KAAa,EACbC,KAAsD;IAEtD,MAAMR,OAA6B;QAAEO;QAAOD;OAAYE,gBAAAA,QAAS,CAAC;IAClE,OAAOP,SAASC,IAAI,CAACF,MAAM;QAAEG;QAAQC,SAASN;IAAS;AACzD;AAEA,OAAO,SAASW,yBAAyBC,KAAa;IACpD,OAAOT,SAASC,IAAI,CAClB;QAAEK,OAAO;QAAsBD,QAAQ;IAAqB,GAC5D;QAAEH,QAAQ;QAAKC,SAAS,aAAKN;YAAUa,OAAOD;;IAAQ;AAE1D;AAEA,mEAAmE,GACnE,OAAO,eAAeE,qBAAqBC,OAAgB;IACzD,MAAMb,OAAO,MAAMa,QAAQX,IAAI,GAAGY,KAAK,CAAC,IAAM;IAC9C,OAAOd,QAAQ,OAAOA,SAAS,YAAY,CAACe,MAAMC,OAAO,CAAChB,QACrDA,OACD,CAAC;AACP;AAEA,mEAAmE,GACnE,MAAMiB,cAAc;AAEpB,yDAAyD,GACzD,OAAO,SAASC,uBAAuBC,KAAc;IACnD,MAAMC,KAAK,OAAOD,UAAU,WAAWA,MAAME,IAAI,KAAK;IACtD,OAAOJ,YAAYK,IAAI,CAACF,MAAMA,KAAK;AACrC"}

package/src/lib/routes/sequence-routes.d.ts

@@ -0,0 +1,32 @@
+/**
+ * @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.
+ */
+import type { PluginWebApiHandler } from '@aglyn/aglyn/server';
+import { type OutreachRouteDeps } from './route-deps';
+/** The activity line each lifecycle act writes. */
+export declare const OUTREACH_SEQUENCE_ACTIVITY: {
+    readonly create: "Created a sequence";
+    readonly activate: "Activated a sequence";
+    readonly pause: "Paused a sequence";
+    readonly archive: "Archived a sequence";
+    readonly delete: "Deleted a sequence";
+};
+export interface OutreachSequenceRoutes {
+    save: PluginWebApiHandler;
+    status: PluginWebApiHandler;
+    remove: PluginWebApiHandler;
+}
+export declare function createOutreachSequenceRoutes(deps: OutreachRouteDeps): OutreachSequenceRoutes;

package/src/lib/routes/sequence-routes.js

@@ -0,0 +1,359 @@
+import { _ as _extends } from "@swc/helpers/_/_extends";
+/**
+ * @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.
+ */ import { createResourceUid } from "@aglyn/aglyn/app-utils/create-resource-uid";
+import { applyOutreachEnrollmentEvent } from "../engine/enrollment-state.js";
+import { validateOutreachSequence, validateOutreachSequenceActivation } from "../engine/sequence-validation.js";
+import { OUTREACH_OPEN_ENROLLMENT_STATUSES } from "../engine/gates.js";
+import { outreachEnrolledSequenceIssues, outreachMailboxActivationIssue, readOutreachSequenceDraft } from "../model/sequence-draft.js";
+import { readOutreachComplianceSettingsDoc } from "../storage/compliance-settings-store.js";
+import { outreachOrgCollection, readStoredOutreachEnrollment, readStoredOutreachMailbox, readStoredOutreachSequence } from "../storage/outreach-records.js";
+import { OUTREACH_SEQUENCE_ACTIVITY_TARGET } from "./route-deps.js";
+import { outreachRouteGate } from "./route-gate.js";
+import { outreachMethodNotAllowed, outreachOk, outreachRefusal, readOutreachDocumentId, readOutreachJsonBody } from "./route-http.js";
+/**
+ * THE SEQUENCE ROUTES (AGL-2980): save, activate, pause, archive, delete.
+ *
+ * ## Who may change a sequence
+ *
+ * A sequence sends as the member whose mailbox it names, so it is theirs to
+ * change: the member who connected the mailbox, or an organization owner or
+ * admin, may save it, activate it and send from it — the same two the
+ * mailbox's own routes let manage the mailbox. Anyone with `outreach.use`
+ * may pause or archive any sequence, because stopping mail is never the act
+ * that needs guarding.
+ *
+ * ## Saving
+ *
+ * The draft is read with the editor's reader and judged by the engine's
+ * validator, so the save refuses exactly what the editor showed beside a
+ * field. On top of that, the site must be one of the organization's, the
+ * mailbox one of its connected mailboxes, the countries ones the
+ * organization allows, and — once anyone is enrolled — the steps, site and
+ * mailbox fixed (`outreachEnrolledSequenceIssues`). A new sequence is a
+ * draft; an edit keeps the status it had, and an active sequence stays
+ * active only because the edit passed the same validator activation does.
+ *
+ * ## Activating
+ *
+ * `validateOutreachSequenceActivation`: everything a save refuses on, and an
+ * organization whose footer cannot be written — no legal name, or no postal
+ * address. And its mailbox must be sending (`outreachMailboxActivationIssue`):
+ * chosen, still connected, not paused, and not waiting to be reconnected —
+ * the same words the sequence page shows beside its disabled Activate.
+ *
+ * ## Archiving
+ *
+ * Final. Every person still active or paused in the sequence is stopped
+ * with `sequence_archived`, in batches, so no archived sequence goes on
+ * sending.
+ */ /** A batch holds 500 writes; a page of enrollments stops this many. */ const ARCHIVE_PAGE = 400;
+/** The activity line each lifecycle act writes. */ export const OUTREACH_SEQUENCE_ACTIVITY = {
+    create: 'Created a sequence',
+    activate: 'Activated a sequence',
+    pause: 'Paused a sequence',
+    archive: 'Archived a sequence',
+    delete: 'Deleted a sequence'
+};
+/** Where each action may start, and where it ends. */ const TRANSITIONS = {
+    activate: {
+        from: [
+            'draft',
+            'paused'
+        ],
+        to: 'active'
+    },
+    pause: {
+        from: [
+            'active'
+        ],
+        to: 'paused'
+    },
+    archive: {
+        from: [
+            'draft',
+            'active',
+            'paused'
+        ],
+        to: 'archived'
+    }
+};
+const ACTION_REFUSALS = {
+    activate: 'Only a draft or paused sequence can be activated.',
+    pause: 'Only an active sequence can be paused.',
+    archive: 'This sequence is already archived.'
+};
+async function loadSequence(firestore, orgId, sequenceId) {
+    const snapshot = await outreachOrgCollection(firestore, orgId, 'sequences').doc(sequenceId).get();
+    return readStoredOutreachSequence(sequenceId, snapshot.exists ? snapshot.data() : undefined);
+}
+/** Whether anyone was ever enrolled in the sequence. */ async function hasEnrollments(firestore, orgId, sequenceId) {
+    const found = await outreachOrgCollection(firestore, orgId, 'enrollments').where('sequenceId', '==', sequenceId).limit(1).get();
+    return !found.empty;
+}
+const issue = (path, code, message)=>({
+        path,
+        code,
+        message,
+        severity: 'error'
+    });
+/**
+ * The organization-level facts a draft has to agree with: its site is the
+ * organization's, its mailbox is connected and the caller may send from it,
+ * and its countries are ones the organization allows. `activating` adds
+ * that the mailbox is sending now — chosen, and neither paused nor waiting
+ * to be reconnected.
+ */ async function draftPlacementIssues(firestore, caller, draft, options = {}) {
+    const issues = [];
+    if (draft.hostId) {
+        const host = readOutreachDocumentId(draft.hostId) ? await firestore.collection('hosts').doc(draft.hostId).get() : null;
+        if (!(host == null ? void 0 : host.exists) || host.get('orgId') !== caller.orgId) {
+            issues.push(issue('hostId', 'host_unknown', "Choose one of this organization's sites."));
+        }
+    } else {
+        issues.push(issue('hostId', 'host_unknown', "Choose the site whose contacts this sequence emails."));
+    }
+    const mailbox = draft.mailboxId ? await loadMailbox(firestore, caller.orgId, draft.mailboxId) : null;
+    const activation = options.activating ? outreachMailboxActivationIssue(draft.mailboxId, mailbox) : null;
+    if (draft.mailboxId) {
+        const placement = mailboxIssues(caller, mailbox);
+        // A mailbox that is gone is refused once, in activation's words when
+        // activating: they say what to do next.
+        issues.push(...(activation == null ? void 0 : activation.code) === 'mailbox_unknown' ? placement.filter((entry)=>entry.code !== 'mailbox_unknown') : placement);
+    }
+    if (activation && !issues.some((entry)=>entry.code === 'mailbox_not_yours')) issues.push(activation);
+    const settings = await readOutreachComplianceSettingsDoc(firestore, caller.orgId);
+    const outside = draft.settings.allowedCountries.filter((code)=>!settings.allowedCountries.includes(code));
+    if (outside.length) {
+        issues.push(issue('settings.allowedCountries', 'country_not_in_org', `${outside.join(', ')} ${outside.length === 1 ? "isn't" : "aren't"} among the countries your organization allows. Add ${outside.length === 1 ? 'it' : 'them'} in Sequences compliance settings first.`));
+    }
+    return issues;
+}
+/** A mailbox of this organization's, as stored; `null` when there is none by that id. */ async function loadMailbox(firestore, orgId, mailboxId) {
+    const snapshot = readOutreachDocumentId(mailboxId) ? await outreachOrgCollection(firestore, orgId, 'mailboxes').doc(mailboxId).get() : null;
+    return readStoredOutreachMailbox(mailboxId, (snapshot == null ? void 0 : snapshot.exists) ? snapshot.data() : undefined);
+}
+/** Whether the mailbox is connected here, and the caller may send from it. */ function mailboxIssues(caller, mailbox) {
+    if (!mailbox || mailbox.status === 'disconnected') {
+        return [
+            issue('mailboxId', 'mailbox_unknown', 'That mailbox is not connected to this organization.')
+        ];
+    }
+    if (mailbox.connectedByUid !== caller.uid && !caller.isOrgAdmin) {
+        return [
+            issue('mailboxId', 'mailbox_not_yours', 'Only the member who connected this mailbox, or an organization owner or admin, can send from it.')
+        ];
+    }
+    return [];
+}
+/** One issue per field and code: activation and the engine can both ask for a mailbox. */ function distinctIssues(issues) {
+    const seen = new Set();
+    return issues.filter((entry)=>{
+        const key = `${entry.path}|${entry.code}`;
+        if (seen.has(key)) return false;
+        seen.add(key);
+        return true;
+    });
+}
+export function createOutreachSequenceRoutes(deps) {
+    const activity = (caller, action, sequence)=>deps.logOrgActivity(caller.orgId, {
+            uid: caller.uid,
+            email: caller.email
+        }, action, {
+            type: OUTREACH_SEQUENCE_ACTIVITY_TARGET,
+            id: sequence.id,
+            name: sequence.name
+        });
+    const save = async (request)=>{
+        var _ref;
+        if (request.method !== 'POST') return outreachMethodNotAllowed('POST');
+        const body = await readOutreachJsonBody(request);
+        const caller = await outreachRouteGate(request, body['orgId'], deps.gate);
+        if (caller instanceof Response) return caller;
+        const firestore = deps.firestore();
+        const rawId = body['sequenceId'];
+        const sequenceId = rawId === undefined || rawId === null || rawId === '' ? null : readOutreachDocumentId(rawId);
+        if (rawId && !sequenceId) return outreachRefusal(400, 'invalid-request', 'Name the sequence to save.');
+        const existing = sequenceId ? await loadSequence(firestore, caller.orgId, sequenceId) : null;
+        if (sequenceId && !existing) {
+            return outreachRefusal(404, 'sequence-not-found', 'That sequence no longer exists.');
+        }
+        if ((existing == null ? void 0 : existing.status) === 'archived') {
+            return outreachRefusal(409, 'sequence-archived', "An archived sequence can't be edited.");
+        }
+        const draft = readOutreachSequenceDraft(body['sequence']);
+        // A sequence sends as its mailbox's member, so it is theirs (or an
+        // admin's) to change — the stored mailbox as well as a new one: moving
+        // a colleague's sequence onto your own mailbox is still changing theirs.
+        if ((existing == null ? void 0 : existing.mailboxId) && existing.mailboxId !== draft.mailboxId) {
+            const stored = mailboxIssues(caller, await loadMailbox(firestore, caller.orgId, existing.mailboxId));
+            const refused = stored.find((entry)=>entry.code === 'mailbox_not_yours');
+            if (refused) return outreachRefusal(403, 'permission', refused.message);
+        }
+        const judged = [
+            ...validateOutreachSequence(draft),
+            ...await draftPlacementIssues(firestore, caller, draft)
+        ];
+        const ownership = judged.find((entry)=>entry.code === 'mailbox_not_yours');
+        if (ownership) return outreachRefusal(403, 'permission', ownership.message);
+        if (existing && await hasEnrollments(firestore, caller.orgId, existing.id)) {
+            judged.push(...outreachEnrolledSequenceIssues(existing, draft));
+        }
+        const errors = judged.filter((entry)=>entry.severity === 'error');
+        if (errors.length) {
+            return outreachRefusal(400, 'invalid-sequence', errors[0].message, {
+                issues: judged
+            });
+        }
+        const nowMs = deps.now();
+        const ref = existing ? outreachOrgCollection(firestore, caller.orgId, 'sequences').doc(existing.id) : outreachOrgCollection(firestore, caller.orgId, 'sequences').doc(createResourceUid());
+        const sequence = _extends({
+            id: ref.id
+        }, draft, {
+            status: (_ref = existing == null ? void 0 : existing.status) != null ? _ref : 'draft',
+            createdAtMs: (existing == null ? void 0 : existing.createdAtMs) || nowMs,
+            updatedAtMs: nowMs
+        });
+        await ref.set(sequence);
+        if (!existing) await activity(caller, OUTREACH_SEQUENCE_ACTIVITY.create, sequence);
+        return outreachOk({
+            ok: true,
+            sequence,
+            created: !existing,
+            warnings: judged.filter((entry)=>entry.severity === 'warning')
+        });
+    };
+    const status = async (request)=>{
+        if (request.method !== 'POST') return outreachMethodNotAllowed('POST');
+        const body = await readOutreachJsonBody(request);
+        const caller = await outreachRouteGate(request, body['orgId'], deps.gate);
+        if (caller instanceof Response) return caller;
+        const action = body['action'];
+        const sequenceId = readOutreachDocumentId(body['sequenceId']);
+        if (!sequenceId || !Object.prototype.hasOwnProperty.call(TRANSITIONS, action)) {
+            return outreachRefusal(400, 'invalid-request', 'Name the sequence, and activate, pause or archive.');
+        }
+        const firestore = deps.firestore();
+        const sequence = await loadSequence(firestore, caller.orgId, sequenceId);
+        if (!sequence) return outreachRefusal(404, 'sequence-not-found', 'That sequence no longer exists.');
+        const transition = TRANSITIONS[action];
+        if (sequence.status === transition.to) {
+            return outreachOk({
+                ok: true,
+                sequence,
+                stoppedEnrollments: 0
+            });
+        }
+        if (!transition.from.includes(sequence.status)) {
+            return outreachRefusal(409, 'transition-refused', ACTION_REFUSALS[action]);
+        }
+        if (action === 'activate') {
+            const orgSettings = await readOutreachComplianceSettingsDoc(firestore, caller.orgId);
+            const judged = distinctIssues([
+                ...validateOutreachSequenceActivation(sequence, orgSettings),
+                ...await draftPlacementIssues(firestore, caller, sequence, {
+                    activating: true
+                })
+            ]).filter((entry)=>entry.severity === 'error');
+            if (judged.length) {
+                const ownership = judged.find((entry)=>entry.code === 'mailbox_not_yours');
+                return ownership ? outreachRefusal(403, 'permission', ownership.message) : outreachRefusal(409, 'activation-refused', judged[0].message, {
+                    issues: judged
+                });
+            }
+        }
+        const nowMs = deps.now();
+        const next = _extends({}, sequence, {
+            status: transition.to,
+            updatedAtMs: nowMs
+        });
+        await outreachOrgCollection(firestore, caller.orgId, 'sequences').doc(sequence.id).update({
+            status: next.status,
+            updatedAtMs: nowMs
+        });
+        const stoppedEnrollments = action === 'archive' ? await stopOpenEnrollments(firestore, caller, sequence.id, nowMs) : 0;
+        await activity(caller, OUTREACH_SEQUENCE_ACTIVITY[action], sequence);
+        return outreachOk({
+            ok: true,
+            sequence: next,
+            stoppedEnrollments
+        });
+    };
+    const remove = async (request)=>{
+        if (request.method !== 'POST') return outreachMethodNotAllowed('POST');
+        const body = await readOutreachJsonBody(request);
+        const caller = await outreachRouteGate(request, body['orgId'], deps.gate);
+        if (caller instanceof Response) return caller;
+        const sequenceId = readOutreachDocumentId(body['sequenceId']);
+        if (!sequenceId) return outreachRefusal(400, 'invalid-request', 'Name the sequence to delete.');
+        const firestore = deps.firestore();
+        const sequence = await loadSequence(firestore, caller.orgId, sequenceId);
+        if (!sequence) return outreachRefusal(404, 'sequence-not-found', 'That sequence no longer exists.');
+        if (sequence.status !== 'draft' || await hasEnrollments(firestore, caller.orgId, sequence.id)) {
+            // What people were sent, and why they stopped, is the record of what
+            // this organization did; only a draft nobody was enrolled in has none.
+            return outreachRefusal(409, 'delete-refused', 'Only a draft nobody was enrolled in can be deleted. Archive this sequence instead.');
+        }
+        await outreachOrgCollection(firestore, caller.orgId, 'sequences').doc(sequence.id).delete();
+        await activity(caller, OUTREACH_SEQUENCE_ACTIVITY.delete, sequence);
+        return outreachOk({
+            ok: true
+        });
+    };
+    return {
+        save,
+        status,
+        remove
+    };
+}
+/**
+ * Stops everyone still active or paused in an archived sequence, a page at
+ * a time, through the engine's own transition. Returns how many it stopped.
+ */ async function stopOpenEnrollments(firestore, caller, sequenceId, nowMs) {
+    const enrollments = outreachOrgCollection(firestore, caller.orgId, 'enrollments');
+    let stopped = 0;
+    let after = null;
+    for(;;){
+        let page = enrollments.where('sequenceId', '==', sequenceId).orderBy('__name__').limit(ARCHIVE_PAGE);
+        if (after) page = page.startAfter(after);
+        const snapshot = await page.get();
+        if (snapshot.empty) break;
+        const batch = firestore.batch();
+        let writes = 0;
+        for (const doc of snapshot.docs){
+            const enrollment = readStoredOutreachEnrollment(doc.id, doc.data());
+            if (!enrollment || !OUTREACH_OPEN_ENROLLMENT_STATUSES.includes(enrollment.status)) continue;
+            const { patch } = applyOutreachEnrollmentEvent(enrollment, {
+                type: 'stop',
+                reason: 'sequence_archived',
+                atMs: nowMs,
+                byUid: caller.uid
+            });
+            if (!patch) continue;
+            batch.update(doc.ref, _extends({}, patch, {
+                updatedAtMs: nowMs
+            }));
+            writes += 1;
+        }
+        if (writes) await batch.commit();
+        stopped += writes;
+        after = snapshot.docs[snapshot.docs.length - 1];
+        if (snapshot.size < ARCHIVE_PAGE) break;
+    }
+    return stopped;
+}
+
+//# sourceMappingURL=sequence-routes.js.map