@expresscsv/sdk 0.1.17 → 0.1.18

package/README.md

@@ -5,6 +5,8 @@
 
 A TypeScript SDK for embedding the [ExpressCSV](https://expresscsv.com) CSV import widget into any web application. Define a schema, open the widget, and receive validated, typed data in chunks.
 
+If you want to define schemas in shared or backend code without any frontend dependencies, use [`@expresscsv/schemas`](https://www.npmjs.com/package/@expresscsv/schemas) for the schema definition itself, then pass that schema into `@expresscsv/sdk`.
+
 ## Installation
 
 ```bash
@@ -55,6 +57,8 @@ importer.open({
 });
 ```
 
+If your schema is assembled dynamically at runtime, use `x.dynamicRow(...)` instead of `x.row(...)`. It keeps the same runtime parsing behavior while intentionally widening TypeScript inference for runtime-built shapes.
+
 Your `publishableKey` is available from the [ExpressCSV dashboard](https://expresscsv.com). Two key types are available: **production** keys for live usage, and **dev/testing** keys that provide unlimited test imports.
 
 ## Webhook Delivery
@@ -112,6 +116,8 @@ interface WebhookPayload {
 }
 ```
 
+When you already have a schema, prefer `InferWebhookPayload<typeof schema>` from `@expresscsv/schemas` instead of rewriting this object shape by hand.
+
 Example payload:
 
 ```json
@@ -150,6 +156,25 @@ Your endpoint should return a **2xx** status code to acknowledge each chunk. Non
 
 Chunks are delivered **serially** — the next chunk is only sent after the previous one succeeds.
 
+If your schema is defined in shared or backend code with `@expresscsv/schemas`, you can reuse the built-in webhook payload helper when handling deliveries:
+
+```typescript
+import express from "express";
+import type { InferWebhookPayload } from "@expresscsv/schemas";
+import { employeeSchema } from "../shared/employee-schema";
+
+const app = express();
+app.use(express.json());
+
+app.post("/webhooks/csv-import", async (req, res) => {
+  const payload = req.body as InferWebhookPayload<typeof employeeSchema>;
+
+  await db.insertMany("users", payload.records);
+
+  res.status(200).json({ ok: true });
+});
+```
+
 Below is a minimal Express.js example:
 
 ```typescript
@@ -375,6 +400,8 @@ const importer = new CSVImporter({
 
 The `x` schema builder provides a type-safe, fluent API for defining your CSV structure.
 
+For apps that share schema definitions with backend code or webhook handlers, prefer defining the schema in `@expresscsv/schemas` and importing it into your frontend. That keeps schema authoring free of widget/runtime dependencies.
+
 ### Field Types
 
 ```typescript
@@ -413,6 +440,63 @@ const schema = x.row({
 });
 ```
 
+### Runtime-Built Schemas
+
+For a fixed schema, keep everything in a normal `x.row(...)` definition:
+
+```typescript
+const schema = x.row({
+  email: x.string().email().label("Email"),
+  lifecycleStage: x
+    .select([
+      { label: "Lead", value: "lead" },
+      { label: "Customer", value: "customer" },
+      { label: "Churned", value: "churned" },
+    ])
+    .label("Lifecycle Stage"),
+  accountOwner: x.string().label("Account Owner").optional(),
+  contractValue: x.number().currency("USD").label("Contract Value").optional(),
+});
+```
+
+`x.dynamicRow(...)` lets you build the row at runtime, which is useful when the schema depends on account data, user preferences, or enabled custom fields.
+
+```typescript
+import { x } from "@expresscsv/sdk";
+
+function buildCustomerSchema(options: {
+  collectCrmId: boolean;
+  collectHealthScore: boolean;
+  collectSegment: boolean;
+}) {
+  return x.dynamicRow({
+    email: x.string().email().label("Email"),
+    companyName: x.string().label("Company Name"),
+    ...(options.collectCrmId ? { crmId: x.string().label("CRM ID") } : {}),
+    ...(options.collectHealthScore
+      ? { healthScore: x.number().label("Health Score") }
+      : {}),
+    ...(options.collectSegment
+      ? {
+          segment: x
+            .select([
+              { label: "SMB", value: "smb" },
+              { label: "Mid-Market", value: "mid-market" },
+              { label: "Enterprise", value: "enterprise" },
+            ])
+            .label("Segment"),
+        }
+      : {}),
+  });
+}
+
+const schema = buildCustomerSchema({
+  collectCrmId: true,
+  collectHealthScore: true,
+  collectSegment: false,
+});
+```
+
 ### Common Modifiers
 
 All field types support:

package/dist/index.d.cts

@@ -3129,6 +3129,13 @@ declare class ExRow<T extends ExRowShape> extends ExType<{
      * @returns A new ExRow instance
      */
     static create<T extends ExRowShape>(shape: T): ExRow<T>;
+    /**
+     * Factory method for runtime-built row shapes.
+     *
+     * This intentionally widens the returned type to ExRow<ExRowShape> so callers
+     * can assemble fields conditionally without relying on exact key inference.
+     */
+    static createDynamic(shape: ExRowShape): ExRow<ExRowShape>;
     /**
      * Specifies columns that can be null/optional with conditional logic
      *
@@ -3930,6 +3937,7 @@ export declare const x: {
     time: typeof ExTime.create;
     datetime: typeof ExDatetime.create;
     row: typeof ExRow.create;
+    dynamicRow: typeof ExRow.createDynamic;
     select: typeof ExSelect.create;
     multiselect: typeof ExMultiselect.create;
     infer: <T extends ExType<unknown, ExBaseDef, unknown>>(_schema: T) => Infer<T>;

package/dist/index.d.mts

@@ -3129,6 +3129,13 @@ declare class ExRow<T extends ExRowShape> extends ExType<{
      * @returns A new ExRow instance
      */
     static create<T extends ExRowShape>(shape: T): ExRow<T>;
+    /**
+     * Factory method for runtime-built row shapes.
+     *
+     * This intentionally widens the returned type to ExRow<ExRowShape> so callers
+     * can assemble fields conditionally without relying on exact key inference.
+     */
+    static createDynamic(shape: ExRowShape): ExRow<ExRowShape>;
     /**
      * Specifies columns that can be null/optional with conditional logic
      *
@@ -3930,6 +3937,7 @@ export declare const x: {
     time: typeof ExTime.create;
     datetime: typeof ExDatetime.create;
     row: typeof ExRow.create;
+    dynamicRow: typeof ExRow.createDynamic;
     select: typeof ExSelect.create;
     multiselect: typeof ExMultiselect.create;
     infer: <T extends ExType<unknown, ExBaseDef, unknown>>(_schema: T) => Infer<T>;

package/dist/index.d.ts

@@ -3129,6 +3129,13 @@ declare class ExRow<T extends ExRowShape> extends ExType<{
      * @returns A new ExRow instance
      */
     static create<T extends ExRowShape>(shape: T): ExRow<T>;
+    /**
+     * Factory method for runtime-built row shapes.
+     *
+     * This intentionally widens the returned type to ExRow<ExRowShape> so callers
+     * can assemble fields conditionally without relying on exact key inference.
+     */
+    static createDynamic(shape: ExRowShape): ExRow<ExRowShape>;
     /**
      * Specifies columns that can be null/optional with conditional logic
      *
@@ -3930,6 +3937,7 @@ export declare const x: {
     time: typeof ExTime.create;
     datetime: typeof ExDatetime.create;
     row: typeof ExRow.create;
+    dynamicRow: typeof ExRow.createDynamic;
     select: typeof ExSelect.create;
     multiselect: typeof ExMultiselect.create;
     infer: <T extends ExType<unknown, ExBaseDef, unknown>>(_schema: T) => Infer<T>;