sinfactura-types 1.0.90 → 1.0.95

package/README.md

@@ -1,24 +1,50 @@
 # `sinfactura-types`
 
-sinfactura.com interfaces and types.
-updated
+Shared TypeScript type definitions for the SINFACTURA platform. Published as the `sinfactura-types` npm package and consumed by the other SINFACTURA repositories (primarily `app` and `web`) to ensure the backend, admin UI, and storefront agree on the shape of every domain entity: users, stores, customers, products, orders, invoices, baskets, notifications, and more.
 
-## Usage
+## About the SINFACTURA Platform
+
+This repository is part of the SINFACTURA monorepo — an integrated e-commerce, electronic invoicing, and business management suite for the Argentine market.
+
+| Repository                                               | Purpose                                                 | Stack                          |
+| -------------------------------------------------------- | ------------------------------------------------------- | ------------------------------ |
+| [`api`](https://github.com/sinfactura/api)               | Serverless backend — REST + WebSocket APIs              | AWS CDK, Lambda, DynamoDB      |
+| [`app`](https://github.com/sinfactura/app)               | B2B operations & admin platform (internal)              | React 19 + Vite + MUI v7       |
+| [`web`](https://github.com/sinfactura/web)               | Customer-facing e-commerce storefront (TODOINSUMOS)     | React 19 + Vite + MUI v7       |
+| [`landing`](https://github.com/sinfactura/landing)       | Marketing website (sinfactura.com)                      | React 19 + Vite + MUI v7       |
+| [`cloudprint`](https://github.com/sinfactura/cloudprint) | Desktop print agent — receives print jobs via WebSocket | Electron 41 + Vite + SQLite    |
+| **`types`** _(this repo)_                                | Shared TypeScript types                                 | `sinfactura-types` npm package |
+
+## Purpose
+
+`sinfactura-types` is the single source of truth for cross-repo TypeScript interfaces. Rather than duplicating domain shapes (e.g. `User`, `Order`, `Invoice`) in each client, every consumer imports them from this package so that a change to a server-side contract propagates to all clients at build time.
+
+The package contains only TypeScript type declarations — no runtime code. Zod schemas for validation stay co-located in the repos that need them (e.g. `app/` keeps its Zod schemas local; see the root `CLAUDE.md`).
+
+## Installation
 
-```js
+```bash
+# In a SINFACTURA consumer repo (app, web, etc.)
 yarn add --dev sinfactura-types
-npm install -d sinfactura-types
 ```
 
-## Documentation
+## Usage
 
-See https://github.com/sinfactura/types
+```typescript
+import type { IUser, IOrder, IInvoice, IProduct } from "sinfactura-types";
+```
 
-## Build a new version
+## Publishing a New Version
 
-```js
-package.json: "version" attribute ++
+1. Bump the `version` field in `package.json` (follow semver)
+2. Publish to npm:
 
+```bash
 yarn publish
-
 ```
+
+3. In each consumer repo, bump the `sinfactura-types` dependency (e.g. `app` currently uses `^1.0.90`)
+
+## License
+
+Proprietary — Copyright © 2025-2026 SINFACTURA LLC. All rights reserved.

package/dist/audit.d.ts

@@ -0,0 +1,35 @@
+declare global {
+    interface OrderAudit {
+        storeId: string;
+        auditId: string;
+        orderId: string;
+        userId: string;
+        fullName?: string;
+        action: OrderAuditAction;
+        createdAt: number;
+        dated: number;
+        changes?: OrderAuditChange[];
+        itemChanges?: {
+            added: Partial<BasketItem>[];
+            removed: Partial<BasketItem>[];
+            modified: Array<{
+                productId: string;
+                name?: string;
+                oldQuantity: number;
+                newQuantity: number;
+                oldPrice: number;
+                newPrice: number;
+            }>;
+        };
+        oldTotal?: number;
+        newTotal?: number;
+        returnId?: string;
+    }
+    interface OrderAuditChange {
+        field: string;
+        oldValue: unknown;
+        newValue: unknown;
+    }
+    type OrderAuditAction = 'order_created' | 'order_edited' | 'order_ready' | 'order_delivered' | 'order_delivery_cancelled' | 'order_disabled' | 'order_enabled' | 'order_returned' | 'discount_changed' | 'payment_method_changed' | 'delivery_method_changed' | 'delivery_address_changed' | 'invoice_created' | 'credit_note_created';
+}
+export {};

package/dist/audit.js

@@ -0,0 +1 @@
+export {};

package/dist/index.d.ts

@@ -1,6 +1,7 @@
 export * from "./account";
 export * from "./afip";
 export * from "./api";
+export * from "./audit";
 export * from "./auth";
 export * from "./basket";
 export * from "./brands";
@@ -14,8 +15,10 @@ export * from "./maintenance";
 export * from "./notification";
 export * from "./order";
 export * from "./product";
+export * from "./return";
 export * from "./stock";
 export * from "./store";
+export * from "./subscription";
 export * from "./supplier";
 export * from "./user";
 export * from "./whatsapp";

package/dist/index.js

@@ -1,6 +1,7 @@
 export * from "./account";
 export * from "./afip";
 export * from "./api";
+export * from "./audit";
 export * from "./auth";
 export * from "./basket";
 export * from "./brands";
@@ -14,8 +15,10 @@ export * from "./maintenance";
 export * from "./notification";
 export * from "./order";
 export * from "./product";
+export * from "./return";
 export * from "./stock";
 export * from "./store";
+export * from "./subscription";
 export * from "./supplier";
 export * from "./user";
 export * from "./whatsapp";

package/dist/order.d.ts

@@ -25,6 +25,7 @@ declare global {
         orderPrinted?: boolean;
         tagPrinted?: boolean;
         invoices?: Partial<Invoice>[];
+        returns?: Partial<Return>[];
         disabled?: boolean;
         items: Partial<BasketItem>[];
         rating?: number;

package/dist/return.d.ts

@@ -0,0 +1,35 @@
+declare global {
+    interface Return {
+        storeId: string;
+        returnId: string;
+        orderId: string;
+        customerId: string;
+        invoiceId?: string;
+        creditNoteId?: string;
+        items: ReturnItem[];
+        subtotal: number;
+        cost: number;
+        total: number;
+        reason: ReturnReason;
+        notes?: string;
+        userId: string;
+        emitCreditNote: boolean;
+        sendEmail: boolean;
+        creditNoteEmitted: boolean;
+        createdAt: number;
+        dated: number;
+    }
+    interface ReturnItem {
+        productId: string;
+        name: string;
+        sku?: string;
+        quantity: number;
+        price: number;
+        cost: number;
+        ivaType: number;
+        condition: 'sellable' | 'damaged';
+        restock: boolean;
+    }
+    type ReturnReason = 'defective' | 'wrong_item' | 'damaged_shipping' | 'customer_changed_mind' | 'not_as_described' | 'duplicate_order' | 'price_adjustment' | 'billing_error' | 'other';
+}
+export {};

package/dist/return.js

@@ -0,0 +1 @@
+export {};

package/dist/subscription.d.ts

@@ -0,0 +1,147 @@
+/**
+ * Subscription types — plan tiers, entitlements, feature matrix, subscription state.
+ *
+ * Ships app#710 (Chunk 1). Canonical decisions live in
+ * sinfactura/app/docs/plans/SUBSCRIPTION_BUSINESS_DECISIONS.md.
+ *
+ * Notes:
+ * - Tier names are the 4 locked Spanish tiers (per SUBSCRIPTION_TIERS_BEST_PRACTICES §0).
+ * - `fundador` is a `SubscriptionStatus` on `negocio`-tier plans (ADR-0009).
+ * - `FeatureKey` uses flat camelCase (not the dotted `reports.advanced` from the design kit).
+ * - Monetary amounts are integers in minor units (ARS cents) to avoid float issues.
+ * - WhatsApp-specific feature keys + `customDomain` are intentionally OUT of scope here;
+ *   they ship with their own epics (#1072, #1152) after Product sign-off.
+ */
+declare global {
+    type PlanTier = 'basico' | 'emprendedor' | 'negocio' | 'empresa';
+    /**
+     * Lifecycle status of a tenant's subscription.
+     *
+     * - `trialing` — new signup in the 30-day NEGOCIO trial (no payment method).
+     * - `active` — paid subscription, period current.
+     * - `past_due` — payment failed, in the 7-day grace window.
+     * - `readonly` — grace elapsed, writes blocked, tenant can still read.
+     * - `canceled` — tenant ended subscription; data retained per grace policy.
+     * - `fundador` — pre-launch cohort, 12-month free NEGOCIO entitlements (ADR-0009).
+     */
+    type SubscriptionStatus = 'trialing' | 'active' | 'past_due' | 'readonly' | 'canceled' | 'fundador';
+    type BillingCycle = 'monthly' | 'annual';
+    /**
+     * Shape of a single entitlement on a (tier, feature) cell.
+     *
+     * - `boolean`  — on/off gate. `enabled` is the only relevant field.
+     * - `numeric`  — hard cap; `limit` required; block on overage.
+     * - `metered`  — usage-tracked; `limit` required. At launch behaves the same as
+     *                `numeric` (counter-based enforcement, no overage billing). Kept
+     *                distinct so post-launch metered billing can flip behavior without
+     *                a migration.
+     */
+    type EntitlementType = 'boolean' | 'numeric' | 'metered';
+    interface Entitlement {
+        type: EntitlementType;
+        enabled: boolean;
+        /** Required for `numeric` and `metered`. `Infinity`-equivalent — treat sentinel value for "unlimited". */
+        limit?: number;
+    }
+    /**
+     * All gated features. Add new keys here when a new feature becomes gateable;
+     * every existing plan in `FEATURE_MATRIX` must then declare the new key
+     * (TypeScript enforces this via `Record<FeatureKey, Entitlement>`).
+     */
+    type FeatureKey = 'maxOrdersMonth' | 'maxInvoicesMonth' | 'maxProducts' | 'maxUsers' | 'maxCustomers' | 'maxStores' | 'afip' | 'stripePayments' | 'suppliers' | 'cash' | 'multiStore' | 'importExport' | 'reportsAdvanced' | 'customBranding' | 'apiAccess' | 'prioritySupport';
+    /** Full feature matrix — every tier declares every feature. */
+    type FeatureMatrix = Record<PlanTier, Record<FeatureKey, Entitlement>>;
+    /** Resolved entitlements for a specific tenant (matrix + overrides applied). */
+    type ResolvedEntitlements = Record<FeatureKey, Entitlement>;
+    /**
+     * A sellable plan in the catalog. Seeded into DynamoDB by api#626 and
+     * served to the frontend via GET /subscription/plans.
+     *
+     * Prices are integers in ARS cents (e.g. $40 000 = 4_000_000).
+     * `null` = "Contactar ventas" (EMPRESA, pre-unlock).
+     */
+    interface Plan {
+        tier: PlanTier;
+        /** Display label — "BÁSICO", "EMPRENDEDOR", "NEGOCIO", "EMPRESA". */
+        label: string;
+        /** Short marketing tagline (Spanish). */
+        blurb?: string;
+        /** Price in ARS cents for monthly billing. `null` = contactar. */
+        priceMonthly: number | null;
+        /** Price in ARS cents for annual billing (total / 12; ~20% discount). `null` = contactar. */
+        priceAnnual: number | null;
+        /** 'ARS' at launch. Reserved for future multi-currency. */
+        currency: 'ARS';
+        /**
+         * Whether the plan is accepting new subscribers. Closed-cohort plans
+         * (e.g. Founders after 2026-05-31) set this to `false` without deleting
+         * the plan row.
+         */
+        isActive: boolean;
+        /** Marked as the anchor / recommended tier on the pricing page. NEGOCIO at launch. */
+        isPopular?: boolean;
+        /**
+         * Visibility on the public pricing page. EMPRESA = `false` until
+         * ≥2 Planned features ship (per SUBSCRIPTION_TIERS_BEST_PRACTICES §0).
+         */
+        isPublic: boolean;
+        /** Stripe Price IDs once the plan is wired to Stripe Products (api#627). */
+        stripeMonthlyPriceId?: string;
+        stripeAnnualPriceId?: string;
+        /** Per-tier entitlement configuration. */
+        entitlements: Record<FeatureKey, Entitlement>;
+        createdAt: number;
+        updatedAt: number;
+    }
+    /**
+     * A tenant's current subscription row. One per `tenantId`.
+     * Stored in DynamoDB; mirrored to Stripe when `stripeSubscriptionId` is present.
+     */
+    interface Subscription {
+        tenantId: string;
+        planTier: PlanTier;
+        status: SubscriptionStatus;
+        billingCycle: BillingCycle;
+        /** Current period window (Unix ms). */
+        currentPeriodStart: number;
+        currentPeriodEnd: number;
+        /** Set while `status === 'trialing'`. Unix ms. */
+        trialEndsAt?: number;
+        /** Set while `status === 'fundador'`. Unix ms. Per ADR-0009: 2027-06-30T00:00:00Z. */
+        freeUntil?: number;
+        /** Stripe identifiers (absent for trialing/fundador before checkout). */
+        stripeCustomerId?: string;
+        stripeSubscriptionId?: string;
+        /**
+         * Per-tenant entitlement overrides (grandfathering). Applied on top of the
+         * plan's base entitlements when resolving.
+         */
+        overrides?: Partial<Record<FeatureKey, Entitlement>>;
+        createdAt: number;
+        updatedAt: number;
+    }
+    /**
+     * Per-tenant, per-period usage counters for `metered` features. Monthly reset
+     * via scheduled Lambda (api#629). At launch, used only for local enforcement;
+     * not reported to Stripe Meter (metered billing is a post-launch concern).
+     */
+    interface UsageCounters {
+        tenantId: string;
+        /** Period start (Unix ms). Aligns with `Subscription.currentPeriodStart`. */
+        periodStart: number;
+        periodEnd: number;
+        /** Counters keyed by the metered-feature FeatureKey. Keys default to 0 when absent. */
+        counters: Partial<Record<FeatureKey, number>>;
+        updatedAt: number;
+    }
+    /**
+     * Full subscription snapshot pushed to the frontend on subscription/entitlement
+     * changes. Consumers use this to invalidate RTK Query caches and re-render gates.
+     */
+    interface SubscriptionSyncPayload {
+        subscription: Subscription;
+        entitlements: ResolvedEntitlements;
+        usage?: UsageCounters;
+    }
+}
+export {};

package/dist/subscription.js

@@ -0,0 +1,15 @@
+/**
+ * Subscription types — plan tiers, entitlements, feature matrix, subscription state.
+ *
+ * Ships app#710 (Chunk 1). Canonical decisions live in
+ * sinfactura/app/docs/plans/SUBSCRIPTION_BUSINESS_DECISIONS.md.
+ *
+ * Notes:
+ * - Tier names are the 4 locked Spanish tiers (per SUBSCRIPTION_TIERS_BEST_PRACTICES §0).
+ * - `fundador` is a `SubscriptionStatus` on `negocio`-tier plans (ADR-0009).
+ * - `FeatureKey` uses flat camelCase (not the dotted `reports.advanced` from the design kit).
+ * - Monetary amounts are integers in minor units (ARS cents) to avoid float issues.
+ * - WhatsApp-specific feature keys + `customDomain` are intentionally OUT of scope here;
+ *   they ship with their own epics (#1072, #1152) after Product sign-off.
+ */
+export {};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "sinfactura-types",
-  "version": "1.0.90",
+  "version": "1.0.95",
   "main": "dist/index.js",
   "type": "module",
   "types": "./dist/index.d.ts",
@@ -12,7 +12,13 @@
   },
   "scripts": {
     "build": "tsc",
-    "prepublishOnly": "tsc"
+    "prepublishOnly": "tsc",
+    "login": "npm login",
+    "release": "npm version patch --no-git-tag-version && npm publish"
+  },
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/"
   },
   "repository": {
     "type": "git",