@sixtyninecommerce/admin 0.10.0 → 0.12.0

package/dist/integrations/afas-types.d.ts

@@ -0,0 +1,483 @@
+/**
+ * The shapes of `admin.integrations.afas` (headless W10-53): the store's AFAS Profit connection,
+ * the AFAS lists its settings pick from, the warehouse mapping, and the customer payment terms.
+ */
+/** The AFAS article that carries money-only lines at one VAT rate. */
+export interface AfasCorrectionArticle {
+    /** A percentage: `21`, `9`, `5.5`. */
+    taxRate: number;
+    itemCode: string;
+}
+/**
+ * The store's AFAS Profit connection. The App Connector token is WRITE-ONLY: no read returns it
+ * in any form, so this shape has no member for it.
+ */
+export interface AfasConfig {
+    id: string;
+    channelId: string;
+    /** Mirroring is on: activated orders, customers and invoices go to AFAS. */
+    enabled: boolean;
+    /**
+     * The AFAS environment number (`89990`) or its environment code (`T89990AA`). A stored id of
+     * another shape makes every AFAS call refuse `AFAS_CONFIG_INVALID` on `environmentId` before
+     * anything is sent.
+     */
+    environmentId: string;
+    /** `production`, `test` or `accept`. */
+    environmentType: string;
+    orderConnectorId: string;
+    orgCustomerConnectorId: string;
+    perCustomerConnectorId: string;
+    defaultCurrency: string;
+    /** The condition new AFAS debtors get; empty when none is set (never defaulted). */
+    defaultPaymentCondition: string;
+    defaultWarehouse: string | null;
+    defaultAdministration: string | null;
+    paymentTermsEnabled: boolean;
+    paymentConditionConnectorId: string | null;
+    balanceConnectorId: string | null;
+    balanceDebtorFieldId: string | null;
+    balanceAmountFieldId: string | null;
+    invoiceReportConnectorId: string | null;
+    invoiceReportFilterFieldId: string | null;
+    debtorVatDuty: string | null;
+    debtorCollectionAccount: string | null;
+    shippingItemCode: string | null;
+    discountItemCode: string | null;
+    /** One article per VAT rate, for credit notes, free-form and discount rows. */
+    correctionArticleCodes: AfasCorrectionArticle[];
+    /** Kept for older connections; AFAS resolves the unit per article, and nothing sets it now. */
+    directInvoiceUnitCode: string | null;
+    directInvoiceJournalId: string | null;
+    /** ISO-8601. */
+    createdAt: string;
+    /** ISO-8601. */
+    updatedAt: string;
+}
+/** Why an article was picked for a VAT rate when the correction articles were filled from AFAS. */
+export type AfasCorrectionArticleReason = 'DISCOUNT_ITEM' | 'DISCOUNT_KEYWORD' | 'TEXT_LINE' | 'ROUNDING' | 'OTHER';
+/** An article written into a VAT rate that had none. */
+export interface AfasDetectedCorrectionArticle extends AfasCorrectionArticle {
+    description: string;
+    reason: AfasCorrectionArticleReason;
+}
+/** What filling the correction articles from AFAS did, per VAT rate of the store. */
+export interface AfasCorrectionArticleFill {
+    /** The VAT rates the store charges on its catalogue. */
+    storeRates: number[];
+    /** Articles written into a rate that had none. */
+    filled: AfasDetectedCorrectionArticle[];
+    /** Rates that already had an article; left as they were. */
+    kept: number[];
+    /** Rates AFAS has no candidate article for: still to be entered by hand. */
+    unmatchedRates: number[];
+    /** Set only when detection could not run (e.g. `AFAS_READ_FAILED`). */
+    errorCode: string | null;
+    /** What to do about `errorCode`. */
+    error: string | null;
+}
+/** A save's answer: the connection, and what the save filled in from AFAS. */
+export interface AfasConfigSaveResult extends AfasConfig {
+    /**
+     * The correction articles the save detected for the VAT rates that had none, when it left AFAS
+     * on with a token; null otherwise. A detection failure never fails the save: it is reported
+     * here (`errorCode`, `error`).
+     */
+    correctionArticleFill: AfasCorrectionArticleFill | null;
+}
+/**
+ * A PATCH of the connection: a key left out keeps the stored value. The first save must carry
+ * `environmentId` and `token`. The token is write-only: absent, null or empty keeps the stored
+ * one.
+ */
+export interface UpdateAfasConfigInput {
+    enabled?: boolean;
+    environmentId?: string;
+    environmentType?: string;
+    /**
+     * The App Connector token: the whole `<token><version>1</version><data>…</data></token>`
+     * envelope, or only its hex data (32 characters or more), which the engine wraps.
+     */
+    token?: string;
+    orderConnectorId?: string;
+    orgCustomerConnectorId?: string;
+    perCustomerConnectorId?: string;
+    defaultCurrency?: string;
+    /** An empty string clears it. */
+    defaultPaymentCondition?: string;
+    defaultWarehouse?: string | null;
+    defaultAdministration?: string | null;
+    paymentTermsEnabled?: boolean;
+    paymentConditionConnectorId?: string | null;
+    balanceConnectorId?: string | null;
+    balanceDebtorFieldId?: string | null;
+    balanceAmountFieldId?: string | null;
+    invoiceReportConnectorId?: string | null;
+    invoiceReportFilterFieldId?: string | null;
+    directInvoiceJournalId?: string | null;
+    debtorVatDuty?: string | null;
+    debtorCollectionAccount?: string | null;
+    shippingItemCode?: string | null;
+    discountItemCode?: string | null;
+    /** Replaces the whole per-VAT-rate article list; an empty list clears it. */
+    correctionArticleCodes?: AfasCorrectionArticle[];
+}
+/** What the connection test found: a result, not a refusal. */
+export interface AfasConnectionVerification {
+    connected: boolean;
+    /** What the successful connection filled in; null when not connected. */
+    correctionArticles: AfasCorrectionArticleFill | null;
+}
+/**
+ * Values the connected AFAS environment suggests for the settings. Each is null when the
+ * connector behind it is unauthorised, empty or unreadable.
+ */
+export interface AfasDiscoveredDefaults {
+    /** The first administration (`AdminCd`). */
+    administration: string | null;
+    /** The first warehouse that is not blocked. */
+    warehouse: string | null;
+    /** The administration's home currency. */
+    currency: string | null;
+    /** The most common debtor payment condition. */
+    paymentCondition: string | null;
+    vatDuty: string | null;
+    collectionAccount: string | null;
+}
+/**
+ * One attempt to send one record to AFAS. The request the engine sent and AFAS's raw answer are
+ * deliberately not read here: they carry customers' personal data and are kept as audit
+ * evidence, not as an API.
+ */
+export interface AfasSyncLog {
+    id: string;
+    channelId: string;
+    /** `order`, `customer`, `stock_transfer`, … */
+    entityType: string;
+    entityId: string;
+    /** AFAS's reference for the record, when it answered one. */
+    externalRef: string | null;
+    eventType: string;
+    /** `pending`, `success`, `failed` or `skipped`. */
+    status: string;
+    /** AFAS's HTTP status; null when it never answered. */
+    responseStatus: number | null;
+    /** Why it failed, in a sentence for staff; null otherwise. */
+    error: string | null;
+    attempt: number;
+    durationMs: number | null;
+    /** ISO-8601. */
+    createdAt: string;
+}
+/** Which attempts `syncLogs` lists; every member narrows, and none means all. */
+export interface AfasSyncLogFilter {
+    entityType?: string;
+    entityId?: string;
+    status?: string;
+}
+/** An administration of the AFAS environment. */
+export interface AfasAdministration {
+    adminCd: string;
+    adminNm: string;
+    adminId: number | null;
+}
+/** A warehouse of the AFAS environment (`Profit_Warehouses`). */
+export interface AfasWarehouse {
+    code: string;
+    /** Null when the connector exposes no description. */
+    name: string | null;
+    blocked: boolean;
+}
+/** A stock location of the store paired with the AFAS warehouse its stock moves are booked on. */
+export interface AfasWarehouseMapping {
+    id: string;
+    channelId: string;
+    stockLocationId: string;
+    /** The stock location's name, joined for display. */
+    stockLocationName: string | null;
+    /** The AFAS `Profit_Warehouses.Warehouse` code (at most 15 characters). */
+    afasWarehouse: string;
+    /** ISO-8601. */
+    createdAt: string;
+    /** ISO-8601. */
+    updatedAt: string;
+}
+/** One row of the store's AFAS payment-condition catalog. */
+export interface AfasPaymentCondition {
+    id: string;
+    /** AFAS's condition code (`PayCon`). */
+    code: string;
+    description: string | null;
+    /** The payment term in days; null while not mapped. */
+    days: number | null;
+    dueImmediately: boolean;
+    /** Where the row came from: the AFAS catalog, a debtor seen with it, or a merchant edit. */
+    source: string;
+    active: boolean;
+    /** ISO-8601; null for a row no sync has touched. */
+    lastSyncedAt: string | null;
+    /** ISO-8601. */
+    createdAt: string;
+    /** ISO-8601. */
+    updatedAt: string;
+}
+/** The health of the payment-terms mirror and catalog. */
+export interface AfasPaymentTermsStatus {
+    enabled: boolean;
+    connectorId: string | null;
+    conditionCount: number;
+    /** Conditions with no day mapping yet. */
+    unmappedConditionCount: number;
+    linkedCustomers: number;
+    assigned: number;
+    unassigned: number;
+    unresolved: number;
+    stale: number;
+    /** ISO-8601; null before the first sync. */
+    lastSyncedAt: string | null;
+}
+/** What a payment-terms sync did. */
+export interface AfasPaymentTermsSyncResult {
+    catalogConnectorId: string | null;
+    catalogRows: number;
+    catalogCreated: number;
+    catalogUpdated: number;
+    /** Why the catalog could not be read; the customer mirror still ran. */
+    catalogError: string | null;
+    customersLinked: number;
+    customersMatched: number;
+    customersUnassigned: number;
+    customersUnresolved: number;
+}
+/** A merchant's edit of one condition (created when the code is new); never overwritten by a sync. */
+export interface UpdateAfasPaymentConditionInput {
+    code: string;
+    days?: number | null;
+    dueImmediately?: boolean;
+    description?: string | null;
+    active?: boolean;
+}
+/**
+ * How an AFAS debtor row is classified. Drives which `KnSalesRelation*` connector a push uses.
+ * `UNKNOWN` when the store's `Profit_Debtor` connector exposes no classifier field: the engine
+ * then falls back to whether the customer is a business.
+ */
+export type AfasDebtorKind = 'ORGANISATION' | 'PERSON' | 'UNKNOWN';
+/** An AFAS debtor (Verkooprelatie), as AFAS answers it. */
+export interface AfasCustomerPreview {
+    /** The AFAS organisation or person number (BcCo). */
+    bcCo: string;
+    /** The Verkooprelatie code (DbId) a customer is linked by. */
+    debtorId: string;
+    name: string;
+    kind: AfasDebtorKind;
+    email: string | null;
+    phone: string | null;
+    vatNumber: string | null;
+    kvkNumber: string | null;
+    addressLine1: string | null;
+    addressLine3: string | null;
+    addressLine4: string | null;
+    currency: string | null;
+    paymentCondition: string | null;
+    blocked: boolean;
+}
+/** An AFAS sales order, as AFAS answers it. */
+export interface AfasOrderPreview {
+    orNu: string;
+    debtorBcCo: string | null;
+    reference: string | null;
+    orderDate: string | null;
+    /**
+     * AFAS's own figure, a DECIMAL in major units of `currency` (`121.5`), not the platform's
+     * integer minor units: never compare it with an order's `totalWithTax` unconverted.
+     */
+    totalAmount: number | null;
+    currency: string | null;
+    status: string | null;
+    /** True once AFAS marks it "Afgehandeld" (settled): it awaits the accountant's invoice. */
+    settled: boolean;
+}
+/** An AFAS delivery address, as AFAS answers it. */
+export interface AfasAddressPreview {
+    adId: string;
+    bcCo: string | null;
+    street: string | null;
+    houseNumber: number | null;
+    postalCode: string | null;
+    city: string | null;
+    countryCode: string | null;
+}
+/** What pushing an order or a customer to AFAS did. */
+export interface AfasPushResult {
+    success: boolean;
+    /** AFAS holds the sales order as invoiced; the platform stopped sending edits to it. */
+    locked: boolean;
+    /** The order was already in AFAS, so nothing was written (`success` stays true). */
+    alreadySynced: boolean;
+    /** The AFAS number of what was written (the sales order, or the debtor). */
+    externalRef: string | null;
+    /** A note for an outcome that is not an error ("already synced"). */
+    message: string | null;
+    /** Why it did not succeed; AFAS's reason, made readable. */
+    error: string | null;
+    /** The stable code of a refusal named before anything was sent, e.g. `AFAS_EXTERNAL_LINE_ARTICLE_UNSET`. */
+    errorCode: string | null;
+}
+/**
+ * Which AFAS path an order is on. The two are exclusive per order (mixing them books stock and
+ * receivables twice): `SALES_ORDER` (pushed with `orders.sync`, then `orders.settle`) or
+ * `DIRECT_INVOICE` (`orders.createDirectInvoice`); `NONE` before either.
+ */
+export type AfasOrderPath = 'SALES_ORDER' | 'DIRECT_INVOICE' | 'NONE';
+/** An order's AFAS state, read from the platform (no AFAS call). */
+export interface AfasOrderState {
+    path: AfasOrderPath;
+    afasSalesOrderId: string | null;
+    afasSettled: boolean;
+    /** The AFAS packing slip number (`OrNu`) of the direct invoice. */
+    afasDirectInvoiceOrNu: string | null;
+    /** The AFAS invoice number (the V-number). */
+    afasInvoiceNumber: string | null;
+    /** The AFAS invoice date, `YYYY-MM-DD`. */
+    afasInvoiceDate: string | null;
+    /** An invoice report connector is set, so `orders.invoicePdf` can answer a PDF. */
+    hasPdfReport: boolean;
+    /**
+     * The order's state lets it be pushed as a sales order or a direct invoice: false in `Draft`,
+     * `AddingItems`, `ArrangingPayment` and `Cancelled`, where both refuse
+     * `AFAS_ORDER_STATE_BLOCKS_PUSH`. Says nothing of the path rules.
+     */
+    stateAllowsPush: boolean;
+    /** As `stateAllowsPush`, for settling from prepaid credit, which `ArrangingPayment` allows. */
+    stateAllowsPrepaidSettlement: boolean;
+}
+/** What settling an AFAS sales order did. */
+export interface AfasSettleResult {
+    success: boolean;
+    locked: boolean;
+    afasSettled: boolean;
+    error: string | null;
+}
+/** What creating an AFAS direct invoice did. */
+export interface AfasDirectInvoiceResult {
+    success: boolean;
+    afasDirectInvoiceOrNu: string | null;
+    /** Resolved after the insert when AFAS answers it in time; null otherwise (filled later). */
+    afasInvoiceNumber: string | null;
+    afasInvoiceDate: string | null;
+    error: string | null;
+    /** The stable code of a refusal named before anything was sent. */
+    errorCode: string | null;
+}
+/**
+ * Why a stock transfer cannot be sent to AFAS now. Open on `string`: a newer engine may add a
+ * reason.
+ */
+export type AfasStockTransferBlockReason = 'AFAS_DISABLED' | 'NO_ADMINISTRATION' | 'STOCK_TRANSFER_UNSUPPORTED' | 'NOT_FOUND' | 'INVALID_STATE' | 'NO_LINES' | 'RETURN_BOTH_WAREHOUSES_MAPPED' | 'RETURN_NO_MAPPED_WAREHOUSE' | 'RETURN_NOT_RECEIVED' | 'RETURN_RECEIPT_UNKNOWN' | 'RETURN_NOTHING_RECEIVED' | 'NOTHING_LEFT_SOURCE' | (string & {});
+/** Which way sending a stock transfer moves AFAS stock. */
+export type AfasStockTransferDirection = 'DEDUCT' | 'ADD';
+/** A stock transfer's AFAS state, read from the platform (no AFAS call). */
+export interface AfasStockTransferState {
+    enabled: boolean;
+    pushed: boolean;
+    afasDirectInvoiceOrNu: string | null;
+    afasInvoiceNumber: string | null;
+    afasDebtorId: string | null;
+    pushedAt: string | null;
+    /** The AFAS warehouse of the source location; once pushed, the one the document was booked on. */
+    sourceAfasWarehouse: string | null;
+    /** The AFAS warehouse of the destination; null when unmapped, unread, or pushed. */
+    destinationAfasWarehouse: string | null;
+    /** True for a return of another transfer; null when the transfer could not be read. */
+    isReturn: boolean | null;
+    /** Null once pushed, and when the mapping allows no push. */
+    stockDirection: AfasStockTransferDirection | null;
+    pushable: boolean;
+    blockReason: AfasStockTransferBlockReason | null;
+}
+/** What sending a stock transfer to AFAS did. */
+export interface AfasStockTransferInvoiceResult {
+    success: boolean;
+    /** A document already existed: nothing was written to AFAS again. */
+    alreadyPushed: boolean;
+    afasDirectInvoiceOrNu: string | null;
+    afasInvoiceNumber: string | null;
+    error: string | null;
+}
+/**
+ * A customer's outstanding AFAS balance, read live.
+ *
+ * - `linked: false`: AFAS is off, or the customer has no AFAS debtor; use the platform ledger.
+ * - `linked: true, available: false`: AFAS could not be read; fall back to the ledger.
+ * - `linked: true, available: true`: `balance` is AFAS's figure.
+ */
+export interface AfasCustomerBalance {
+    linked: boolean;
+    available: boolean;
+    /** Minor units, signed (positive: the customer owes); null when not available. */
+    balance: number | null;
+    currencyCode: string | null;
+    debtorId: string | null;
+}
+/** The AFAS debtor a customer is linked to. */
+export interface AfasDebtorLink {
+    /** The Verkooprelatie code (DbId). */
+    afasVrId: string;
+    /** The organisation or person number (BcCo); send it, or the next push matches by name. */
+    afasBcCo?: string | null;
+    afasKind?: AfasDebtorKind | null;
+}
+/** How `orders.sync` and `orders.createDirectInvoice` resolve the order's customer in AFAS. */
+export interface AfasOrderCustomerInput {
+    /**
+     * An existing Verkooprelatie (DbId) to link before pushing, or `null` to create a new debtor.
+     * Ignored when the customer is already linked.
+     */
+    customerAfasVrId?: string | null;
+    /** The linked debtor's BcCo; send it with `customerAfasVrId`. */
+    customerAfasBcCo?: string | null;
+    customerAfasKind?: AfasDebtorKind | null;
+}
+/** `orders.sync`'s choices beyond the order. */
+export interface SyncAfasOrderInput extends AfasOrderCustomerInput {
+    /** An existing AFAS delivery address for billing, or `null` to send the address inline. */
+    billingAddressAfasId?: string | null;
+    /** An existing AFAS delivery address for shipping, or `null` to send the address inline. */
+    shippingAddressAfasId?: string | null;
+}
+/** `orders.createDirectInvoice`'s choices beyond the order. */
+export interface CreateAfasDirectInvoiceInput extends AfasOrderCustomerInput {
+    /**
+     * Settle from prepaid credit: a €0 document (every line fully discounted) that books no
+     * receivable but keeps the lines, so AFAS deducts the stock. Allowed in `ArrangingPayment`.
+     */
+    settleAsZeroValue?: boolean;
+}
+/** One of the customer's addresses paired with an AFAS delivery address. */
+export interface AfasAddressMatchInput {
+    vendureAddressId: string;
+    /** An existing AFAS delivery address, or `null` to create one. */
+    afasAddressId?: string | null;
+}
+/** `customers.sync`'s choices beyond the customer. */
+export interface SyncAfasCustomerInput {
+    /** An existing Verkooprelatie (DbId) to link, or `null` to create a new debtor. */
+    afasVrId?: string | null;
+    afasBcCo?: string | null;
+    afasKind?: AfasDebtorKind | null;
+    addressMatches?: AfasAddressMatchInput[];
+}
+/** What `customers.search` looks for; at least one of email, phone or name. */
+export interface AfasCustomerSearchFilter {
+    email?: string;
+    phone?: string;
+    name?: string;
+    /** How many debtors to answer, 1 to `AFAS_CUSTOMER_SEARCH_LIMIT` (50); 10 by default. */
+    limit?: number;
+}
+/** What `stockTransfers.createInvoice` books the transfer against. */
+export interface CreateAfasStockTransferInvoiceInput {
+    /** The AFAS relation (DbId) the €0 document is booked on; a transfer has no customer. */
+    afasDebtorId: string;
+}

package/dist/integrations/afas-types.js

@@ -0,0 +1,5 @@
+/**
+ * The shapes of `admin.integrations.afas` (headless W10-53): the store's AFAS Profit connection,
+ * the AFAS lists its settings pick from, the warehouse mapping, and the customer payment terms.
+ */
+export {};