Insert the customer row. Nothing else.
This used to create the customer AND its primary organization in one
transaction, because customer.organization_id and
organization.customer_id pointed at each other and neither row could be
written standalone with both ends populated. That data-model cycle forced a
package cycle: customer-services had to reach into entity-services for
organizations, related people, entity events and RouteFusion onboarding —
while entity-services needed customers, so it read them through a
hand-written structural port to keep tsc --build able to order the graph.
organization.is_main_org replaced the customer-side pointer, so the
reference is one-directional and the primary org is created through the
ordinary OrganizationService.create({ isMainOrg: true }) path.
@cfxlabsinc/onboarding-services sequences the two, and this method is
back to what a create on a leaf service should be: one insert plus its
cache invalidation.
Returns a ProvisioningCustomer, not a Customer: the primary
org does not exist yet, so the org-derived fields (organizationId,
legalEntityName) have no value to carry and the customer is not yet
visible to get/search.
Idempotent on a caller-supplied id: re-running the same onboarding
attempt hits the customer.external_id unique constraint and returns
DUPLICATE, which the onboarding activity treats as "already done" rather
than inserting a second customer.
Optionalid?: stringOptional pre-generated external id (cust_…). When provided it's
inserted as externalId, overriding the nanoId("cust") column default
— lets the onboarding workflow mint the id up front and reuse it as the
Temporal workflowId, which is also what makes this create idempotent.
Omit to auto-generate.
Drop this customer's cached reads.
Lives here rather than on the writer because it's the cache's own
concern — it names the folded-get keys and the customer tag — so both
the reader (CustomerQueryService) and the writer (CustomerService)
inherit it. The actual caller is customerOnboardingActivities
(@cfxlabsinc/onboarding-services), which calls this once a primary
organization exists for the customer: a customer is invisible to
get/search until its primary org exists, so every read taken earlier
in onboarding cached a negative entry with a 24h L2 TTL, and this is what
clears it.
Bust every cached page — consumer or admin — that a write touching
customerIds could have affected.
The collection tag is always cleared alongside, because an unscoped admin page carries only that tag and no customer id can reach it.
keys deletes exact entries in addition to the tag surgery, passing the
key arguments — this cache hashes and prefixes them. It exists because
invalidateTag resolves keys through the FT index, which does not exist in
memory mode (valkeyClient: null); there the tag bust is a total no-op, and
an exact-key delete is the only thing that keeps read-after-write honest.
Services that folded get onto search pass that get's arguments.
These deletes only reach this instance's own key space, because the key space is partitioned per surface. That is sufficient, and a writer must not try to name the other surface's key:
get entry is itself tagged (by customer
id, or by the collection tag when unscoped), so the tag bust above already
evicts it from the shared L2 and publishes the peer eviction.Mark a customer FAILED after its onboarding run failed terminally.
Separate from update() because a customer can fail BEFORE its primary
organization is created, and update() returns a Customer, which
by definition has one. Idempotent.
Customer↔org activation join: the customer flips ACTIVE only once BOTH
sides are done — provisioning (data.provisionedAt set, recorded by
createCustomerWorkflow's final step) AND the primary org itself ACTIVE
(AiPrise-approved, and RouteFusion-verified too when RF-enabled — see
resolveOrganizationActivation in @cfxlabsinc/entity-services).
Called from BOTH sides of that race — the workflow end (the org may already be ACTIVE) and the org-ACTIVE transition (provisioning may already be done) — and is safe regardless of which finishes first: it's a pure read-then-maybe-write that no-ops whenever either half is missing, and no-ops when the customer is already ACTIVE.
Reads the primary org's status with a direct query on organizationTable
rather than an injected org service/class: entity-services already
depends on customer-services (OrganizationService imports
CustomerQueryService), so a CustomerQueryService → OrganizationAdminService
edge would cycle back. The raw table read stays a leaf dependency, same as
the existing organizationTable join in search().
OptionalcreatedAt?: DbTimestampCriteriaFilter to customers created within this window.
Optionalids?: string[]OptionalincludeWithoutMainOrg?: IncludeWithoutMainOrgTurn the primary-organization INNER JOIN into a LEFT JOIN, so customers
that have no primary organization yet are returned too — with
organizationId / legalEntityName absent (see
MaybeOnboardedCustomer).
A deliberate, narrow escape hatch from the rule that a Customer
is a fully-onboarded one. The only caller is
OrganizationService.create({ isMainOrg: true }), which has to read the
customer whose primary org it is in the middle of inserting; without this
it can never see it and retries forever. Nothing user-facing should pass
it.
Results are NOT cached when this is set: a half-built customer changes shape within seconds, and the 24h L2 TTL would outlive that by a long way.
Optionalname?: stringOptionalnameLike?: stringOptionalorderBy?: DbOrderByCriterion<Optionalpage?: numberDefaults to 1
OptionalpageSize?: numberDefaults to 50
OptionalpropelauthWorkspaceIds?: string[]Optionalq?: stringUnified free-text search. Case-insensitive substring match against the
customer name, the customer external id (cust_…), or the legal entity
(organization) name. Whitespace-only values are a no-op.
OptionalrouteFusionProgramIds?: string[]Filter to customers enrolled in these RouteFusion program ids
(matched against customer.data.routeFusionProgramId). Backs the admin
RouteFusion program-detail "Enrolled customers" list.
Optionalstatuses?: ("ACTIVE" | "FAILED" | "PENDING")[]Filter to customers in these provisioning-lifecycle statuses.
OptionalupdatedAt?: DbTimestampCriteriaFilter to customers updated within this window.
ProtectedsearchTags to write on a page, derived from the scope the query searched — never from the customers present in the result.
That distinction is load-bearing. An entry tagged with the customer ids in
the page carries no tags when the page is empty, so nothing can ever bust
it and a later create leaves it stale for the full L2 TTL. Tagging by
scope means an empty page still carries the tag for what it searched.
An unscoped read falls back to the collection tag, since no customer-id tag can reach a row whose owner did not exist when the entry was written.
StaticdeserializeThe inverse of serializeCustomer: rehydrates the Date fields.
StaticgetAs getCacheKey, for the get({ propelauthWorkspaceId }) fold.
StaticgetThe exact cache key CustomerQueryService.get({ id }) reads through.
get folds onto search, so its entry is an ordinary single-row search
page — these args must stay identical to the ones get passes
({ ids: [id], pageSize: 1 }, plus search's page default of 1). Every
other filter is undefined there, and serviceCacheKey canonicalizes with
JCS, which drops undefined properties, so naming only the three that are
set produces the same digest. customerCache.test.ts pins the equivalence.
Returns the key arguments; the cache hashes and surface-prefixes them. Never pre-hash at a call site.
StaticserializeCustomer → its JSON-safe form. Safe to call without a Valkey client.
Writes to customers: the insert, the generic update, the terminal-failure stamp, and the customer↔org activation join.
Extends CustomerQueryService — so
get/searchare inherited, and every write busts the instance it reads through, which is what keeps read-after-write correct inside a single request.invalidatecomes from CustomerCache at the root of the hierarchy.Everything the old
create()reached for — organizations, related people, entity events, RouteFusion onboarding — moved toonboarding-services, which sits ABOVE both this package andentity-services. That is what makes the dependency one-directional (onboarding → entity → customer) and letsentity-servicesimportCustomerQueryServicedirectly rather than through a structural port.