@fonderie/customers 1.0.0 → 1.1.1

package/brain/outcomes.md

@@ -0,0 +1,189 @@
+<!-- GENERATED — do not edit. Regenerate with: npm run docs:signatures -->
+
+# @fonderie/customers — outcomes
+
+What this package does to a running app: tables its migrations create,
+rows it seeds, routes it registers. Generated from the migration SQL and
+route tables in source — trust this file instead of reading `dist/` or
+downloading tarballs.
+
+## Database tables (after all migrations)
+
+### `fonderie_addresses`
+
+```sql
+id                       UUID PRIMARY KEY DEFAULT gen_random_uuid()
+country_iso              TEXT NOT NULL
+subdivision1_iso         TEXT
+subdivision2_iso         TEXT
+zip_postal_code          TEXT NOT NULL
+line1                    TEXT
+line2                    TEXT
+unit                     TEXT
+```
+
+### `fonderie_customer_addresses`
+
+```sql
+addr_id                  UUID NOT NULL REFERENCES fonderie_addresses(id) ON DELETE CASCADE
+customer_id              UUID NOT NULL REFERENCES fonderie_customers(id) ON DELETE CASCADE
+label                    TEXT NOT NULL DEFAULT 'service'
+is_primary               BOOLEAN NOT NULL DEFAULT false
+label_id                 UUID REFERENCES fonderie_customer_labels(id)
+CONSTRAINT               fonderie_customer_addresses_label_id_fkey FOREIGN KEY (label_id) REFERENCES fonderie_customer_labels(id) ON DELETE SET NULL
+-- PRIMARY KEY (addr_id, customer_id)
+```
+
+### `fonderie_customer_emails`
+
+```sql
+id                       UUID PRIMARY KEY DEFAULT gen_random_uuid()
+customer_id              UUID NOT NULL REFERENCES fonderie_customers(id) ON DELETE CASCADE
+email                    TEXT NOT NULL
+label                    TEXT NOT NULL DEFAULT 'work'
+is_primary               BOOLEAN NOT NULL DEFAULT false
+created_at               TIMESTAMPTZ NOT NULL DEFAULT now()
+label_id                 UUID REFERENCES fonderie_customer_labels(id)
+CONSTRAINT               fonderie_customer_emails_label_id_fkey FOREIGN KEY (label_id) REFERENCES fonderie_customer_labels(id) ON DELETE SET NULL
+```
+
+### `fonderie_customer_labels`
+
+```sql
+id                       UUID PRIMARY KEY DEFAULT gen_random_uuid()
+type                     fonderie_customer_label_type NOT NULL
+value                    TEXT NOT NULL
+created_at               TIMESTAMPTZ NOT NULL DEFAULT now()
+-- CONSTRAINT uq_fcl_type_value UNIQUE (type, value)
+```
+
+### `fonderie_customer_notes`
+
+```sql
+id                       UUID PRIMARY KEY DEFAULT gen_random_uuid()
+customer_id              UUID NOT NULL REFERENCES fonderie_customers(id) ON DELETE CASCADE
+author_id                UUID
+body                     TEXT NOT NULL
+created_at               TIMESTAMPTZ NOT NULL DEFAULT now()
+updated_at               TIMESTAMPTZ NOT NULL DEFAULT now()
+```
+
+### `fonderie_customer_phones`
+
+```sql
+id                       UUID PRIMARY KEY DEFAULT gen_random_uuid()
+customer_id              UUID NOT NULL REFERENCES fonderie_customers(id) ON DELETE CASCADE
+phone                    TEXT NOT NULL
+label                    TEXT NOT NULL DEFAULT 'mobile'
+is_primary               BOOLEAN NOT NULL DEFAULT false
+created_at               TIMESTAMPTZ NOT NULL DEFAULT now()
+label_id                 UUID REFERENCES fonderie_customer_labels(id)
+CONSTRAINT               fonderie_customer_phones_label_id_fkey FOREIGN KEY (label_id) REFERENCES fonderie_customer_labels(id) ON DELETE SET NULL
+```
+
+### `fonderie_customer_relationships`
+
+```sql
+id                       UUID PRIMARY KEY DEFAULT gen_random_uuid()
+workspace_id             UUID NOT NULL
+customer_id              UUID NOT NULL REFERENCES fonderie_customers(id) ON DELETE CASCADE
+related_id               UUID NOT NULL REFERENCES fonderie_customers(id) ON DELETE CASCADE
+relationship             TEXT NOT NULL
+is_primary               BOOLEAN NOT NULL DEFAULT false
+created_at               TIMESTAMPTZ NOT NULL DEFAULT now()
+-- UNIQUE (customer_id, related_id)
+```
+
+### `fonderie_customer_sequences`
+
+```sql
+workspace_id             UUID NOT NULL
+prefix                   TEXT NOT NULL
+next_val                 BIGINT NOT NULL DEFAULT 1
+-- PRIMARY KEY (workspace_id, prefix)
+```
+
+### `fonderie_customer_tags`
+
+```sql
+customer_id              UUID NOT NULL REFERENCES fonderie_customers(id) ON DELETE CASCADE
+tag                      TEXT NOT NULL
+-- PRIMARY KEY (customer_id, tag)
+```
+
+### `fonderie_customers`
+
+```sql
+id                       UUID PRIMARY KEY DEFAULT gen_random_uuid()
+workspace_id             UUID NOT NULL
+type                     TEXT NOT NULL DEFAULT 'individual'
+first_name               TEXT
+last_name                TEXT
+company_name             TEXT
+avatar_url               TEXT
+locale                   TEXT NOT NULL DEFAULT 'en-US'
+reference_code           TEXT
+is_blacklisted           BOOLEAN NOT NULL DEFAULT false
+created_by               UUID
+created_at               TIMESTAMPTZ NOT NULL DEFAULT now()
+updated_at               TIMESTAMPTZ NOT NULL DEFAULT now()
+sex                      TEXT NOT NULL DEFAULT 'UNKNOWN'
+blacklist_reason         TEXT
+```
+
+Raw SQL ships in `node_modules/@fonderie/customers/dist/migrations/sql/` — read it there if you must; never download tarballs.
+
+## Seeded rows (behavioral contract)
+
+```sql
+INSERT INTO fonderie_customer_labels (type, value) VALUES ('email', 'work'), ('email', 'personal'), ('email', 'billing'), ('phone', 'mobile'), ('phone', 'office'), ('phone', 'home'), ('phone', 'fax'), ('address', 'service'), ('address', 'billing'), ('address', 'other') ON CONFLICT (type, value) DO NOTHING;
+INSERT INTO fonderie_customer_labels (type, value) SELECT DISTINCT 'email'::fonderie_customer_label_type, label FROM fonderie_customer_emails WHERE label IS NOT NULL ON CONFLICT (type, value) DO NOTHING;
+INSERT INTO fonderie_customer_labels (type, value) SELECT DISTINCT 'phone'::fonderie_customer_label_type, label FROM fonderie_customer_phones WHERE label IS NOT NULL ON CONFLICT (type, value) DO NOTHING;
+INSERT INTO fonderie_customer_labels (type, value) SELECT DISTINCT 'address'::fonderie_customer_label_type, label FROM fonderie_customer_addresses WHERE label IS NOT NULL ON CONFLICT (type, value) DO NOTHING;
+```
+
+## HTTP routes registered
+
+| Method | Path | Middleware chain (auth / validation / handler) |
+|---|---|---|
+| GET | `/customers` | `requireAuth → wsCtx → customer.list` |
+| POST | `/customers` | `requireAuth → wsCtx → validate(createCustomerSchema) → customer.create` |
+| DELETE | `/customers/:customerId` | `requireAuth → wsCtx → customer.delete` |
+| GET | `/customers/:customerId` | `requireAuth → wsCtx → customer.get` |
+| PUT | `/customers/:customerId` | `requireAuth → wsCtx → validate(updateCustomerSchema) → customer.update` |
+| GET | `/customers/:customerId/addresses` | `requireAuth → wsCtx → address.list` |
+| POST | `/customers/:customerId/addresses` | `requireAuth → wsCtx → validate(addAddressSchema) → address.add` |
+| DELETE | `/customers/:customerId/addresses/:addrId` | `requireAuth → wsCtx → address.remove` |
+| PATCH | `/customers/:customerId/addresses/:addrId` | `requireAuth → wsCtx → validate(updateAddressSchema) → address.update` |
+| PUT | `/customers/:customerId/addresses/:addrId/primary` | `requireAuth → wsCtx → address.setPrimary` |
+| POST | `/customers/:customerId/blacklist` | `requireAuth → wsCtx → validate(blacklistSchema) → customer.blacklist` |
+| GET | `/customers/:customerId/emails` | `requireAuth → wsCtx → email.list` |
+| POST | `/customers/:customerId/emails` | `requireAuth → wsCtx → validate(addEmailSchema) → email.add` |
+| DELETE | `/customers/:customerId/emails/:emailId` | `requireAuth → wsCtx → email.remove` |
+| PATCH | `/customers/:customerId/emails/:emailId` | `requireAuth → wsCtx → validate(updateEmailSchema) → email.update` |
+| PUT | `/customers/:customerId/emails/:emailId/primary` | `requireAuth → wsCtx → email.setPrimary` |
+| GET | `/customers/:customerId/notes` | `requireAuth → wsCtx → note.list` |
+| POST | `/customers/:customerId/notes` | `requireAuth → wsCtx → validate(noteSchema) → note.create` |
+| DELETE | `/customers/:customerId/notes/:noteId` | `requireAuth → wsCtx → note.delete` |
+| PUT | `/customers/:customerId/notes/:noteId` | `requireAuth → wsCtx → validate(noteSchema) → note.update` |
+| GET | `/customers/:customerId/phones` | `requireAuth → wsCtx → phone.list` |
+| POST | `/customers/:customerId/phones` | `requireAuth → wsCtx → validate(addPhoneSchema) → phone.add` |
+| DELETE | `/customers/:customerId/phones/:phoneId` | `requireAuth → wsCtx → phone.remove` |
+| PATCH | `/customers/:customerId/phones/:phoneId` | `requireAuth → wsCtx → validate(updatePhoneSchema) → phone.update` |
+| PUT | `/customers/:customerId/phones/:phoneId/primary` | `requireAuth → wsCtx → phone.setPrimary` |
+| GET | `/customers/:customerId/relationships` | `requireAuth → wsCtx → relationship.list` |
+| POST | `/customers/:customerId/relationships` | `requireAuth → wsCtx → validate(addRelationshipSchema) → relationship.add` |
+| DELETE | `/customers/:customerId/relationships/:relatedId` | `requireAuth → wsCtx → relationship.remove` |
+| PUT | `/customers/:customerId/relationships/:relatedId/primary` | `requireAuth → wsCtx → relationship.setPrimary` |
+| GET | `/customers/:customerId/tags` | `requireAuth → wsCtx → tag.list` |
+| POST | `/customers/:customerId/tags` | `requireAuth → wsCtx → validate(addTagSchema) → tag.add` |
+| DELETE | `/customers/:customerId/tags/:tag` | `requireAuth → wsCtx → tag.remove` |
+| POST | `/customers/:customerId/unblacklist` | `requireAuth → wsCtx → customer.unblacklist` |
+| GET | `/customers/labels` | `requireAuth → wsCtx → label.list` |
+| DELETE | `/customers/labels/:labelId` | `requireAuth → wsCtx → label.remove` |
+
+## Migration statements not replayed (verify in raw SQL)
+
+- `END IF`
+- `END $$`
+- `CREATE TYPE fonderie_customer_label_type AS ENUM ('email', 'phone', 'address')`

package/brain/signatures.md

@@ -0,0 +1,244 @@
+<!-- GENERATED — do not edit. Regenerate with: npm run docs:signatures -->
+
+# @fonderie/customers — signatures
+
+## @fonderie/customers
+
+Subpath exports: `@fonderie/customers/types`, `@fonderie/customers/migrations`
+
+```ts
+type CustomersEventKey = (typeof EVENT_KEYS)[keyof typeof EVENT_KEYS];
+
+type ICustomersConfig = {
+    referenceCodePrefix?: string;
+};
+
+const EVENT_KEYS: { readonly customerCreated: "fonderie.customer.created"; readonly customerUpdated: "fonderie.customer.updated"; readonly customerDeleted: "fonderie.customer.deleted"; readonly customerBlacklisted: "fonderie.customer.blacklisted"; readonly customerUnblacklisted: "fonderie.customer.unblacklisted"; }
+
+interface IAddressDTO {
+    countryIso: string;
+    subdivision1Iso: string;
+    subdivision2Iso: string;
+    zipPostalCode: string;
+    unit: string;
+    line1: string;
+    line2: string;
+}
+
+interface ICustomerAddressDTO {
+    id: string;
+    label: string;
+    isPrimary: boolean;
+    address: IAddressDTO;
+}
+
+interface ICustomerDetailDTO extends ICustomerDTO {
+    emails: ICustomerEmailDTO[];
+    phones: ICustomerPhoneDTO[];
+    addresses: ICustomerAddressDTO[];
+    notes: ICustomerNoteDTO[];
+    relationships: ICustomerRelationshipExpandedDTO[];
+    tags: string[];
+}
+
+interface ICustomerDTO {
+    id: string;
+    type: string;
+    sex: CustomerSex;
+    firstName: string;
+    lastName: string;
+    companyName: string;
+    avatarUrl: string;
+    locale: string;
+    referenceCode: string;
+    blacklisted: {
+        status: boolean;
+        reason: string | null;
+    };
+    createdBy: string;
+    createdAt: string;
+    updatedAt: string;
+}
+
+interface ICustomerEmailDTO {
+    id: string;
+    email: string;
+    label: string;
+    isPrimary: boolean;
+    createdAt: string;
+}
+
+interface ICustomerNoteDTO {
+    id: string;
+    authorId: string;
+    body: string;
+    createdAt: string;
+    updatedAt: string;
+}
+
+interface ICustomerPhoneDTO {
+    id: string;
+    phone: string;
+    label: string;
+    isPrimary: boolean;
+    createdAt: string;
+}
+
+interface ICustomerTagDTO {
+    tag: string;
+}
+
+function toAddressDTO(a: IAddress): IAddressDTO
+
+function toCustomerAddressDTO(ca: ICustomerAddress): ICustomerAddressDTO
+
+function toCustomerDetailDTO(c: ICustomerDetail): ICustomerDetailDTO
+
+function toCustomerDTO(c: ICustomer): ICustomerDTO
+
+function toCustomerEmailDTO(e: ICustomerEmail): ICustomerEmailDTO
+
+function toCustomerNoteDTO(n: ICustomerNote): ICustomerNoteDTO
+
+function toCustomerPhoneDTO(p: ICustomerPhone): ICustomerPhoneDTO
+
+function toCustomerTagDTO(t: ICustomerTag): ICustomerTagDTO
+
+new CustomerAddressModel(store: IStoreAdapter): CustomerAddressModel
+  .list(customerId: string): Promise<ICustomerAddress[]>
+  .add(opts: { customerId: string; countryIso: string; subdivision1Iso?: string | null; subdivision2Iso?: string | null; zipPostalCode: string; unit?: string | null; line1?: string | null; line2?: string | null; labelId: string; isPrimary?: boolean; }): Promise<...>
+  .updateLabel(addrId: string, customerId: string, labelId: string): Promise<ICustomerAddress>
+  .setPrimary(addrId: string, customerId: string): Promise<void>
+  .remove(addrId: string, customerId: string): Promise<void>
+
+new CustomerEmailModel(store: IStoreAdapter): CustomerEmailModel
+  .list(customerId: string): Promise<ICustomerEmail[]>
+  .add(opts: { customerId: string; email: string; labelId: string; isPrimary?: boolean; }): Promise<ICustomerEmail>
+  .updateLabel(emailId: string, customerId: string, labelId: string): Promise<ICustomerEmail>
+  .setPrimary(emailId: string, customerId: string): Promise<void>
+  .remove(emailId: string, customerId: string): Promise<void>
+
+new CustomerModel(store: IStoreAdapter): CustomerModel
+  .list(opts: ListCustomersOpts): Promise<ICustomer[]>
+  .findById(id: string, workspaceId: string): Promise<ICustomer | null>
+  .findDetail(id: string, workspaceId: string, depth: 2): Promise<ICustomerDetailD2 | null>
+  .create(opts: CreateCustomerOpts): Promise<ICustomer>
+  .update(id: string, workspaceId: string, opts: UpdateCustomerOpts, referenceCodePrefix?: string): Promise<ICustomer | null>
+  .delete(id: string, workspaceId: string): Promise<void>
+  .blacklist(id: string, workspaceId: string, reason?: string | null | undefined): Promise<void>
+  .unblacklist(id: string, workspaceId: string): Promise<void>
+
+new CustomerNoteModel(store: IStoreAdapter): CustomerNoteModel
+  .list(customerId: string): Promise<ICustomerNote[]>
+  .create(opts: { customerId: string; authorId?: string | null; body: string; }): Promise<ICustomerNote>
+  .update(noteId: string, customerId: string, body: string): Promise<ICustomerNote | null>
+  .delete(noteId: string, customerId: string): Promise<void>
+
+new CustomerPhoneModel(store: IStoreAdapter): CustomerPhoneModel
+  .list(customerId: string): Promise<ICustomerPhone[]>
+  .add(opts: { customerId: string; phone: string; labelId: string; isPrimary?: boolean; }): Promise<ICustomerPhone>
+  .updateLabel(phoneId: string, customerId: string, labelId: string): Promise<ICustomerPhone>
+  .setPrimary(phoneId: string, customerId: string): Promise<void>
+  .remove(phoneId: string, customerId: string): Promise<void>
+
+new CustomerTagModel(store: IStoreAdapter): CustomerTagModel
+  .list(customerId: string): Promise<string[]>
+  .add(customerId: string, tag: string): Promise<void>
+  .remove(customerId: string, tag: string): Promise<void>
+
+new CustomersModule(store: IStoreAdapter, config?: ICustomersConfig, bus?: EventBus | undefined): CustomersModule
+  .name: "@fonderie/customers"
+  .deps: string[]
+  .install(app: IFonderieApp): void
+
+type AddressLabel = 'service' | 'billing' | 'other';
+
+type CustomerType = 'individual' | 'business';
+
+type EmailLabel = 'work' | 'personal' | 'billing';
+
+interface IAddress {
+    id: string;
+    countryIso: string;
+    subdivision1Iso: string | null;
+    subdivision2Iso: string | null;
+    zipPostalCode: string;
+    unit: string | null;
+    line1: string | null;
+    line2: string | null;
+}
+
+interface ICustomer {
+    id: string;
+    workspaceId: string;
+    type: CustomerType;
+    sex: CustomerSex;
+    firstName: string | null;
+    lastName: string | null;
+    companyName: string | null;
+    avatarUrl: string | null;
+    locale: string;
+    referenceCode: string | null;
+    isBlacklisted: boolean;
+    blacklistReason: string | null;
+    createdBy: string | null;
+    createdAt: string;
+    updatedAt: string;
+}
+
+interface ICustomerAddress {
+    addrId: string;
+    customerId: string;
+    labelId: string;
+    label: string;
+    isPrimary: boolean;
+    address: IAddress;
+}
+
+interface ICustomerDetail extends ICustomer {
+    emails: ICustomerEmail[];
+    phones: ICustomerPhone[];
+    addresses: ICustomerAddress[];
+    notes: ICustomerNote[];
+    relationships: ICustomerRelationshipExpanded[];
+    tags: string[];
+}
+
+interface ICustomerEmail {
+    id: string;
+    customerId: string;
+    email: string;
+    labelId: string;
+    label: string;
+    isPrimary: boolean;
+    createdAt: string;
+}
+
+interface ICustomerNote {
+    id: string;
+    customerId: string;
+    authorId: string | null;
+    body: string;
+    createdAt: string;
+    updatedAt: string;
+}
+
+interface ICustomerPhone {
+    id: string;
+    customerId: string;
+    phone: string;
+    labelId: string;
+    label: string;
+    isPrimary: boolean;
+    createdAt: string;
+}
+
+interface ICustomerTag {
+    customerId: string;
+    tag: string;
+}
+
+type PhoneLabel = 'mobile' | 'office' | 'home' | 'fax';
+
+namespace schemas — exports: addAddressSchema, addEmailSchema, addPhoneSchema, addRelationshipSchema, addTagSchema, blacklistSchema, createCustomerSchema, noteSchema, updateAddressSchema, updateCustomerSchema, updateEmailSchema, updatePhoneSchema
+```