@memberjunction/actions-apollo 6.1.0-edge.4 → 6.1.0-edge.5

package/dist/lists/ApolloRESTClient.d.ts

@@ -0,0 +1,136 @@
+import type { ApolloAccount, ApolloAccountSearchFilter, ApolloAccountsPage, ApolloContact, ApolloContactSearchFilter, ApolloContactsPage, ApolloLabel, ApolloMoveResult, ApolloPagingOptions, ApolloPeoplePage, ApolloPeopleSearchFilter, IApolloRESTClient } from '../generic/apollo-lists.types.js';
+/** Options for {@link ApolloRESTClient}. */
+export interface ApolloRESTClientOptions {
+    /**
+     * Injected fetch, for tests. Tests must never reach api.apollo.io — a live
+     * call would consume real credits and mutate a real account's lists.
+     */
+    fetchImpl?: typeof fetch;
+}
+/**
+ * Apollo.io list/search client. See the module doc, and the quirk list on
+ * `apollo-lists.types.ts`, for the behaviours it encodes.
+ */
+export declare class ApolloRESTClient implements IApolloRESTClient {
+    private readonly apiKey;
+    private readonly fetchImpl;
+    /**
+     * The label id↔name maps, built on first use and cached for the instance
+     * lifetime (quirk #5). One labels call per client, shared by every search and
+     * move. No TTL: a single drain or move operation uses one instance, and
+     * labels do not churn mid-operation. Construct a new client to see label
+     * changes made since.
+     */
+    private labelMaps;
+    constructor(apiKey: string, options?: ApolloRESTClientOptions);
+    /**
+     * Issue one request and return the parsed body. A non-2xx throws with the
+     * method, path, status and whatever detail Apollo supplied; a 403 on a
+     * master-key operation throws the master-key explanation instead (quirk #4).
+     * Nothing is swallowed — a body that will not parse still surfaces its text.
+     */
+    private request;
+    /**
+     * Every label, account lists and contact lists alike. Master key required.
+     * Apollo returns either a bare array or a `{ labels: [...] }` envelope
+     * depending on the account; both are accepted.
+     */
+    listLabels(): Promise<ApolloLabel[]>;
+    /**
+     * Create a label. Master key required.
+     *
+     * `modality` is not optional to Apollo despite reading like it should be:
+     * posting without it returns HTTP 422 "Please enter a non-empty modality!".
+     * It defaults to 'contacts' here because a people list is the common case.
+     *
+     * The create response shape is not pinned in Apollo's docs, so a bare label
+     * object, a `{ label: {...} }` envelope and a `{ labels: [...] }` envelope
+     * are all accepted — mirroring how {@link listLabels} tolerates two read
+     * shapes. A shape none of those match throws rather than returning a label
+     * with an empty id, which would then be written into a membership array.
+     */
+    createLabel(name: string, modality?: 'contacts' | 'accounts'): Promise<ApolloLabel>;
+    /**
+     * Resolve a label by exact name, case-insensitive; null when nothing matches.
+     * This is how a human-supplied list name becomes the id a search filter needs.
+     */
+    findLabelByName(name: string): Promise<ApolloLabel | null>;
+    /**
+     * Build (once per instance) the id↔name maps that resolve search-response
+     * `label_ids` into names (quirk #5). When two labels share a name — rare — the
+     * last one wins in `nameToId`.
+     */
+    private getLabelMaps;
+    /** One aggregated warning for label ids that did not resolve to a name (quirk #5). */
+    private warnUnresolvedLabels;
+    /**
+     * One page of saved accounts. Paging defaults to page 1 — when draining a
+     * list, never advance (quirk #3).
+     */
+    searchAccounts(filter: ApolloAccountSearchFilter, paging?: ApolloPagingOptions): Promise<ApolloAccountsPage>;
+    /** One page of saved contacts. Same drain-page-1 default as {@link searchAccounts}. */
+    searchContacts(filter: ApolloContactSearchFilter, paging?: ApolloPagingOptions): Promise<ApolloContactsPage>;
+    /**
+     * One page of prospecting people — net-new, not your saved contacts. Apollo
+     * does not return emails or phones here by design.
+     *
+     * Unlike the two searches above, this one does not need the label maps: the
+     * prospecting response carries no memberships, so fetching them would be a
+     * wasted master-key call on a read a scoped key can otherwise serve.
+     */
+    searchPeople(filter: ApolloPeopleSearchFilter, paging?: ApolloPagingOptions): Promise<ApolloPeoplePage>;
+    /**
+     * Replace one account's label set with `labelNames` — which must be the
+     * COMPLETE intended set, because Apollo overwrites wholesale (quirk #1).
+     * Master key required.
+     */
+    private updateAccountLabels;
+    /** The same for one contact. Identical full-replace and master-key semantics. */
+    private updateContactLabels;
+    /**
+     * Re-read one account's current labels for the verify pass (quirk #2), by
+     * searching the destination list and matching on id. Null when the record is
+     * not on that page, which is not the same as "the remove worked" — hence
+     * `possiblyStuck` stays null rather than becoming false.
+     */
+    private readAccountLabels;
+    private readContactLabels;
+    /**
+     * The ADD phase's label set: current ∪ {toList}. Idempotent — adding a label
+     * the record already carries is a set no-op, so re-running a partial move
+     * does not duplicate anything.
+     */
+    private addPhaseLabels;
+    /**
+     * The REMOVE phase's label set: (current ∪ {toList}) \ {fromList}.
+     *
+     * It is computed from the post-add state rather than from `current` so that
+     * the destination label survives the second write. Deriving it from `current`
+     * alone would add the record to the destination and then immediately take it
+     * back out.
+     */
+    private removePhaseLabels;
+    /**
+     * The move engine, shared by accounts and contacts through the injected
+     * update/read closures so the label-preservation math and the stuck detection
+     * exist in exactly one place.
+     */
+    private moveRecords;
+    /**
+     * Move accounts between lists. The supplied accounts must carry current
+     * `labelNames` from a fresh {@link searchAccounts} read — this method writes
+     * whatever it is given as the intended set, so stale labels here mean real
+     * memberships silently disappear.
+     *
+     * With `verify`, the destination list is re-read after each remove to flag
+     * silent-fail records. Never deletes, never auto-retries.
+     */
+    moveAccounts(accounts: ApolloAccount[], fromList: string, toList: string, options?: {
+        verify?: boolean;
+    }): Promise<ApolloMoveResult>;
+    /** Move contacts between lists. Same two-step and verify semantics as accounts. */
+    moveContacts(contacts: ApolloContact[], fromList: string, toList: string, options?: {
+        verify?: boolean;
+    }): Promise<ApolloMoveResult>;
+}
+//# sourceMappingURL=ApolloRESTClient.d.ts.map

package/dist/lists/ApolloRESTClient.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ApolloRESTClient.d.ts","sourceRoot":"","sources":["../../src/lists/ApolloRESTClient.ts"],"names":[],"mappings":"AAoCA,OAAO,KAAK,EACR,aAAa,EACb,yBAAyB,EACzB,kBAAkB,EAClB,aAAa,EACb,yBAAyB,EACzB,kBAAkB,EAClB,WAAW,EAEX,gBAAgB,EAEhB,mBAAmB,EACnB,gBAAgB,EAChB,wBAAwB,EAExB,iBAAiB,EACpB,MAAM,kCAAkC,CAAC;AAO1C,4CAA4C;AAC5C,MAAM,WAAW,uBAAuB;IACpC;;;OAGG;IACH,SAAS,CAAC,EAAE,OAAO,KAAK,CAAC;CAC5B;AA+GD;;;GAGG;AACH,qBAAa,gBAAiB,YAAW,iBAAiB;IACtD,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAS;IAChC,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAe;IACzC;;;;;;OAMG;IACH,OAAO,CAAC,SAAS,CAA0B;gBAE/B,MAAM,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,uBAAuB;IAW7D;;;;;OAKG;YACW,OAAO;IAgErB;;;;OAIG;IACU,UAAU,IAAI,OAAO,CAAC,WAAW,EAAE,CAAC;IAiBjD;;;;;;;;;;;;OAYG;IACU,WAAW,CAAC,IAAI,EAAE,MAAM,EAAE,QAAQ,GAAE,UAAU,GAAG,UAAuB,GAAG,OAAO,CAAC,WAAW,CAAC;IAoC5G;;;OAGG;IACU,eAAe,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,WAAW,GAAG,IAAI,CAAC;IASvE;;;;OAIG;YACW,YAAY;IAmB1B,sFAAsF;IACtF,OAAO,CAAC,oBAAoB;IAW5B;;;OAGG;IACU,cAAc,CAAC,MAAM,EAAE,yBAAyB,EAAE,MAAM,CAAC,EAAE,mBAAmB,GAAG,OAAO,CAAC,kBAAkB,CAAC;IAmBzH,uFAAuF;IAC1E,cAAc,CAAC,MAAM,EAAE,yBAAyB,EAAE,MAAM,CAAC,EAAE,mBAAmB,GAAG,OAAO,CAAC,kBAAkB,CAAC;IAkBzH;;;;;;;OAOG;IACU,YAAY,CAAC,MAAM,EAAE,wBAAwB,EAAE,MAAM,CAAC,EAAE,mBAAmB,GAAG,OAAO,CAAC,gBAAgB,CAAC;IAqBpH;;;;OAIG;YACW,mBAAmB;IAajC,iFAAiF;YACnE,mBAAmB;IAajC;;;;;OAKG;YACW,iBAAiB;YAOjB,iBAAiB;IAO/B;;;;OAIG;IACH,OAAO,CAAC,cAAc;IAItB;;;;;;;OAOG;IACH,OAAO,CAAC,iBAAiB;IAKzB;;;;OAIG;YACW,WAAW;IAqFzB;;;;;;;;OAQG;IACU,YAAY,CACrB,QAAQ,EAAE,aAAa,EAAE,EACzB,QAAQ,EAAE,MAAM,EAChB,MAAM,EAAE,MAAM,EACd,OAAO,CAAC,EAAE;QAAE,MAAM,CAAC,EAAE,OAAO,CAAA;KAAE,GAC/B,OAAO,CAAC,gBAAgB,CAAC;IAgB5B,mFAAmF;IACtE,YAAY,CACrB,QAAQ,EAAE,aAAa,EAAE,EACzB,QAAQ,EAAE,MAAM,EAChB,MAAM,EAAE,MAAM,EACd,OAAO,CAAC,EAAE;QAAE,MAAM,CAAC,EAAE,OAAO,CAAA;KAAE,GAC/B,OAAO,CAAC,gBAAgB,CAAC;CAc/B"}