@base44/app-plugin-commerce 0.1.0

package/base44/entities/commerce.ShippingClass.jsonc

@@ -0,0 +1,30 @@
+{
+  "name": "commerce.ShippingClass",
+  "type": "object",
+  "description": "Shipping class assignable to products; flat-rate methods can charge per class.",
+  "properties": {
+    "name": {
+      "type": "string",
+      "minLength": 1
+    },
+    "slug": {
+      "type": "string",
+      "description": "Unique slug (enforced in admin UI / functions)"
+    },
+    "description": {
+      "type": "string"
+    },
+    "count": {
+      "type": "integer",
+      "default": 0,
+      "description": "Derived product count. Maintained by commerce/admin-products; repair via commerce/admin-tools recount-terms."
+    }
+  },
+  "required": ["name"],
+  "rls": {
+    "read": { "user_condition": { "role": "admin" } },
+    "create": { "user_condition": { "role": "admin" } },
+    "update": { "user_condition": { "role": "admin" } },
+    "delete": { "user_condition": { "role": "admin" } }
+  }
+}

package/base44/entities/commerce.ShippingZone.jsonc

@@ -0,0 +1,41 @@
+{
+  "name": "commerce.ShippingZone",
+  "type": "object",
+  "description": "Geographic shipping zone. Zones are matched by 'order' ascending; the seeded 'Rest of the world' zone (order 999, no locations) catches unmatched addresses.",
+  "properties": {
+    "name": {
+      "type": "string",
+      "minLength": 1
+    },
+    "order": {
+      "type": "integer",
+      "default": 0,
+      "description": "Match priority, ascending"
+    },
+    "locations": {
+      "type": "array",
+      "description": "Zone locations; empty = matches everything (fallback zone)",
+      "items": {
+        "type": "object",
+        "properties": {
+          "type": {
+            "type": "string",
+            "enum": ["country", "state", "postcode", "continent"],
+            "description": "Location type"
+          },
+          "code": {
+            "type": "string",
+            "description": "Country code (US), state code (US:CA), postcode pattern (90*, 1000...2000), or continent code (EU)"
+          }
+        }
+      }
+    }
+  },
+  "required": ["name"],
+  "rls": {
+    "read": { "user_condition": { "role": "admin" } },
+    "create": { "user_condition": { "role": "admin" } },
+    "update": { "user_condition": { "role": "admin" } },
+    "delete": { "user_condition": { "role": "admin" } }
+  }
+}

package/base44/entities/commerce.ShippingZoneMethod.jsonc

@@ -0,0 +1,84 @@
+{
+  "name": "commerce.ShippingZoneMethod",
+  "type": "object",
+  "description": "A shipping method instance attached to a zone. The settings object shape depends on method_id.",
+  "properties": {
+    "zone_id": {
+      "type": "string",
+      "description": "ShippingZone id"
+    },
+    "method_id": {
+      "type": "string",
+      "enum": ["flat_rate", "free_shipping", "local_pickup"],
+      "description": "Method type"
+    },
+    "title": {
+      "type": "string",
+      "description": "Customer-facing method title"
+    },
+    "enabled": {
+      "type": "boolean",
+      "default": true
+    },
+    "order": {
+      "type": "integer",
+      "default": 0,
+      "description": "Display order within the zone"
+    },
+    "settings": {
+      "type": "object",
+      "description": "Per-method settings. flat_rate: {cost, tax_status, class_costs, no_class_cost, calculation_type}; free_shipping: {requires, min_amount, ignore_discounts}; local_pickup: {cost, tax_status}",
+      "properties": {
+        "cost": {
+          "type": "number",
+          "description": "flat_rate/local_pickup base cost"
+        },
+        "tax_status": {
+          "type": "string",
+          "enum": ["taxable", "none"],
+          "description": "flat_rate/local_pickup"
+        },
+        "class_costs": {
+          "type": "array",
+          "description": "flat_rate: additional cost per shipping class present in the cart",
+          "items": {
+            "type": "object",
+            "properties": {
+              "shipping_class_id": { "type": "string" },
+              "cost": { "type": "number" }
+            }
+          }
+        },
+        "no_class_cost": {
+          "type": "number",
+          "description": "flat_rate: cost applied for items without a shipping class"
+        },
+        "calculation_type": {
+          "type": "string",
+          "enum": ["class", "order"],
+          "description": "flat_rate: charge per class present (class) or most expensive class only (order)"
+        },
+        "requires": {
+          "type": "string",
+          "enum": ["", "coupon", "min_amount", "either", "both"],
+          "description": "free_shipping: requirement for the method to be offered"
+        },
+        "min_amount": {
+          "type": "number",
+          "description": "free_shipping: minimum items subtotal"
+        },
+        "ignore_discounts": {
+          "type": "boolean",
+          "description": "free_shipping: compare min_amount against pre-discount subtotal"
+        }
+      }
+    }
+  },
+  "required": ["zone_id", "method_id"],
+  "rls": {
+    "read": { "user_condition": { "role": "admin" } },
+    "create": { "user_condition": { "role": "admin" } },
+    "update": { "user_condition": { "role": "admin" } },
+    "delete": { "user_condition": { "role": "admin" } }
+  }
+}

package/base44/entities/commerce.StoreSettings.jsonc

@@ -0,0 +1,23 @@
+{
+  "name": "commerce.StoreSettings",
+  "type": "object",
+  "description": "Store configuration, one record per settings group. The values object shape is group-specific; seeded by commerce/seed-store. Storefront functions expose only a safe subset via commerce/storefront-catalog get-store-info.",
+  "properties": {
+    "group_id": {
+      "type": "string",
+      "enum": ["general", "products", "inventory", "downloadable", "tax", "shipping", "emails"],
+      "description": "Settings group; unique (one record per group, enforced by seed/admin UI)"
+    },
+    "values": {
+      "type": "object",
+      "description": "Free-form settings for the group"
+    }
+  },
+  "required": ["group_id"],
+  "rls": {
+    "read": { "user_condition": { "role": "admin" } },
+    "create": { "user_condition": { "role": "admin" } },
+    "update": { "user_condition": { "role": "admin" } },
+    "delete": { "user_condition": { "role": "admin" } }
+  }
+}

package/base44/entities/commerce.TaxClass.jsonc

@@ -0,0 +1,23 @@
+{
+  "name": "commerce.TaxClass",
+  "type": "object",
+  "description": "Tax class grouping products for rate matching. Seeded: standard, reduced-rate, zero-rate.",
+  "properties": {
+    "slug": {
+      "type": "string",
+      "minLength": 1,
+      "description": "Unique slug (enforced in admin UI / seed)"
+    },
+    "name": {
+      "type": "string",
+      "minLength": 1
+    }
+  },
+  "required": ["slug", "name"],
+  "rls": {
+    "read": { "user_condition": { "role": "admin" } },
+    "create": { "user_condition": { "role": "admin" } },
+    "update": { "user_condition": { "role": "admin" } },
+    "delete": { "user_condition": { "role": "admin" } }
+  }
+}

package/base44/entities/commerce.TaxRate.jsonc

@@ -0,0 +1,68 @@
+{
+  "name": "commerce.TaxRate",
+  "type": "object",
+  "description": "A tax rate matched by location and tax class. Applied by shared/tax per priority/compound rules.",
+  "properties": {
+    "country": {
+      "type": "string",
+      "default": "",
+      "description": "ISO 3166-1 alpha-2 country code; empty = any"
+    },
+    "state": {
+      "type": "string",
+      "default": "",
+      "description": "State/province code; empty = any"
+    },
+    "postcodes": {
+      "type": "array",
+      "items": { "type": "string" },
+      "description": "Postcode patterns; supports wildcard (90*) and numeric range (1000...2000); empty = any"
+    },
+    "cities": {
+      "type": "array",
+      "items": { "type": "string" },
+      "description": "City names; empty = any"
+    },
+    "rate": {
+      "type": "number",
+      "description": "Percentage rate, e.g. 20 for 20%"
+    },
+    "name": {
+      "type": "string",
+      "minLength": 1,
+      "description": "Label, e.g. VAT"
+    },
+    "priority": {
+      "type": "integer",
+      "default": 1,
+      "description": "Only one matching rate per priority is applied; lower priorities apply first"
+    },
+    "compound": {
+      "type": "boolean",
+      "default": false,
+      "description": "Applied on top of previously accumulated taxes"
+    },
+    "shipping": {
+      "type": "boolean",
+      "default": true,
+      "description": "Rate also applies to shipping"
+    },
+    "tax_class": {
+      "type": "string",
+      "default": "standard",
+      "description": "TaxClass slug this rate belongs to"
+    },
+    "menu_order": {
+      "type": "integer",
+      "default": 0,
+      "description": "Tie-breaker among rates of the same priority"
+    }
+  },
+  "required": ["rate", "name"],
+  "rls": {
+    "read": { "user_condition": { "role": "admin" } },
+    "create": { "user_condition": { "role": "admin" } },
+    "update": { "user_condition": { "role": "admin" } },
+    "delete": { "user_condition": { "role": "admin" } }
+  }
+}

package/base44/entities/commerce.Webhook.jsonc

@@ -0,0 +1,57 @@
+{
+  "name": "commerce.Webhook",
+  "type": "object",
+  "description": "Outgoing webhook definition. Dispatched by shared/commerce/webhooks with X-Commerce-Webhook-* headers and HMAC-SHA256 signature.",
+  "properties": {
+    "name": {
+      "type": "string",
+      "minLength": 1
+    },
+    "status": {
+      "type": "string",
+      "enum": ["active", "paused", "disabled"],
+      "default": "active",
+      "description": "Only active webhooks are delivered; auto-disabled after 5 consecutive failures"
+    },
+    "topic": {
+      "type": "string",
+      "description": "resource.event, e.g. order.created, product.updated"
+    },
+    "resource": {
+      "type": "string",
+      "enum": ["order", "product", "customer", "coupon"],
+      "description": "Derived from topic"
+    },
+    "event": {
+      "type": "string",
+      "enum": ["created", "updated", "deleted", "restored"],
+      "description": "Derived from topic"
+    },
+    "delivery_url": {
+      "type": "string",
+      "format": "uri",
+      "description": "Endpoint receiving POST deliveries"
+    },
+    "secret": {
+      "type": "string",
+      "description": "HMAC-SHA256 signing secret (see skills/commerce/references/webhooks.md on storage tradeoffs)"
+    },
+    "api_version": {
+      "type": "string",
+      "default": "v3",
+      "description": "Payload format version"
+    },
+    "failure_count": {
+      "type": "integer",
+      "default": 0,
+      "description": "Consecutive delivery failures. Maintained by shared/commerce/webhooks; auto-disable at 5."
+    }
+  },
+  "required": ["name", "topic", "delivery_url"],
+  "rls": {
+    "read": { "user_condition": { "role": "admin" } },
+    "create": { "user_condition": { "role": "admin" } },
+    "update": { "user_condition": { "role": "admin" } },
+    "delete": { "user_condition": { "role": "admin" } }
+  }
+}

package/base44/entities/commerce.WebhookDelivery.jsonc

@@ -0,0 +1,45 @@
+{
+  "name": "commerce.WebhookDelivery",
+  "type": "object",
+  "description": "Delivery log for a webhook attempt. Written by shared/commerce/webhooks dispatch; prune via commerce/admin-tools prune-webhook-deliveries.",
+  "properties": {
+    "webhook_id": {
+      "type": "string",
+      "description": "Webhook id"
+    },
+    "topic": {
+      "type": "string"
+    },
+    "delivery_url": {
+      "type": "string"
+    },
+    "request_headers": {
+      "type": "object",
+      "description": "Headers sent with the delivery"
+    },
+    "request_body": {
+      "type": "string",
+      "description": "JSON payload, truncated to 32KB"
+    },
+    "response_code": {
+      "type": "integer"
+    },
+    "response_body": {
+      "type": "string",
+      "description": "Response body, truncated"
+    },
+    "duration_ms": {
+      "type": "number"
+    },
+    "success": {
+      "type": "boolean"
+    }
+  },
+  "required": ["webhook_id"],
+  "rls": {
+    "read": { "user_condition": { "role": "admin" } },
+    "create": { "user_condition": { "role": "admin" } },
+    "update": { "user_condition": { "role": "admin" } },
+    "delete": { "user_condition": { "role": "admin" } }
+  }
+}

package/base44/functions/commerce/admin-coupons/entry.ts

@@ -0,0 +1,100 @@
+/**
+ * commerce/admin-coupons — coupon CRUD with code normalization/uniqueness and webhooks.
+ *
+ * Actions: save | delete | batch | search
+ */
+import { createClientFromRequest } from "npm:@base44/sdk";
+import { HttpError, requireAdmin } from "../../../shared/commerce/auth.ts";
+import { dispatch } from "../../../shared/commerce/webhooks.ts";
+import { pageSlice, scanAll, textMatch } from "../../../shared/commerce/scan.ts";
+
+const ok = (data: unknown, status = 200) => Response.json({ success: true, data }, { status });
+const fail = (status: number, error: string, code?: string) =>
+  Response.json({ success: false, error, code }, { status });
+
+Deno.serve(async (req) => {
+  try {
+    const base44 = createClientFromRequest(req);
+    await requireAdmin(base44);
+    const sr = base44.asServiceRole;
+    const { action, ...payload } = await req.json();
+
+    switch (action) {
+      case "save":
+        return ok(await save(sr, payload.coupon));
+      case "delete":
+        return ok(await remove(sr, payload.id));
+      case "batch":
+        return ok(await batch(sr, payload));
+      case "search": {
+        const { q, limit = 20, skip = 0, sort = "-created_date" } = payload;
+        let rows = await scanAll(sr.entities["commerce.Coupon"], null, sort);
+        if (q) rows = rows.filter((c) => textMatch(c.code, q) || textMatch(c.description, q));
+        return ok(pageSlice(rows, Number(limit), Number(skip)));
+      }
+      default:
+        return fail(400, `Unknown action: ${action}`, "unknown_action");
+    }
+  } catch (e) {
+    if (e instanceof HttpError) return fail(e.status, e.message, e.code);
+    console.error("commerce/admin-coupons error:", e);
+    return fail(500, (e as Error).message ?? "Internal error");
+  }
+});
+
+async function save(sr: any, coupon: any): Promise<any> {
+  if (!coupon) throw new HttpError(400, "coupon is required", "invalid_payload");
+  const code = String(coupon.code ?? "").toLowerCase().trim();
+  if (!code) throw new HttpError(400, "Coupon code is required.", "invalid_payload");
+  if (coupon.amount == null || Number(coupon.amount) < 0) {
+    throw new HttpError(400, "Coupon amount is required.", "invalid_amount");
+  }
+  if (coupon.discount_type === "percent" && Number(coupon.amount) > 100) {
+    throw new HttpError(400, "Percentage discounts cannot exceed 100.", "invalid_amount");
+  }
+
+  const dupes = (await sr.entities["commerce.Coupon"].filter({ code }, undefined, 2)) ?? [];
+  if (dupes.some((c: any) => c.id !== coupon.id)) {
+    throw new HttpError(409, `Coupon code "${code}" already exists.`, "duplicate_code");
+  }
+
+  const { id, created_date: _cd, updated_date: _ud, created_by: _cb, ...fields } = { ...coupon, code };
+  let saved: any;
+  if (id) {
+    const prev = await sr.entities["commerce.Coupon"].get(id);
+    if (!prev) throw new HttpError(404, "Coupon not found", "not_found");
+    await sr.entities["commerce.Coupon"].update(id, fields);
+    saved = { ...prev, ...fields };
+    await dispatch(sr, "coupon.updated", saved);
+  } else {
+    saved = await sr.entities["commerce.Coupon"].create({ usage_count: 0, used_by: [], ...fields });
+    await dispatch(sr, "coupon.created", saved);
+  }
+  return saved;
+}
+
+async function remove(sr: any, id: string): Promise<any> {
+  const coupon = await sr.entities["commerce.Coupon"].get(id);
+  if (!coupon) throw new HttpError(404, "Coupon not found", "not_found");
+  await sr.entities["commerce.Coupon"].delete(id);
+  await dispatch(sr, "coupon.deleted", coupon);
+  return { deleted: id };
+}
+
+async function batch(sr: any, payload: any): Promise<any> {
+  const results = { create: [] as any[], update: [] as any[], delete: [] as any[] };
+  const cap = 100;
+  for (const c of (payload.create ?? []).slice(0, cap)) {
+    try { results.create.push({ success: true, coupon: await save(sr, c) }); }
+    catch (e) { results.create.push({ success: false, error: (e as Error).message }); }
+  }
+  for (const c of (payload.update ?? []).slice(0, cap)) {
+    try { results.update.push({ success: true, coupon: await save(sr, c) }); }
+    catch (e) { results.update.push({ success: false, id: c.id, error: (e as Error).message }); }
+  }
+  for (const id of (payload.delete ?? []).slice(0, cap)) {
+    try { results.delete.push({ success: true, ...(await remove(sr, id)) }); }
+    catch (e) { results.delete.push({ success: false, id, error: (e as Error).message }); }
+  }
+  return results;
+}

package/base44/functions/commerce/admin-customers/entry.ts

@@ -0,0 +1,141 @@
+/**
+ * commerce/admin-customers — customer CRUD, invites and denormalized stats.
+ *
+ * Actions: save | delete | search | invite | recalculate-stats
+ */
+import { createClientFromRequest } from "npm:@base44/sdk";
+import { HttpError, requireAdmin } from "../../../shared/commerce/auth.ts";
+import { round2 } from "../../../shared/commerce/money.ts";
+import { dispatch } from "../../../shared/commerce/webhooks.ts";
+import { pageSlice, scanAll, textMatch } from "../../../shared/commerce/scan.ts";
+
+const ok = (data: unknown, status = 200) => Response.json({ success: true, data }, { status });
+const fail = (status: number, error: string, code?: string) =>
+  Response.json({ success: false, error, code }, { status });
+
+Deno.serve(async (req) => {
+  try {
+    const base44 = createClientFromRequest(req);
+    await requireAdmin(base44);
+    const sr = base44.asServiceRole;
+    const { action, ...payload } = await req.json();
+
+    switch (action) {
+      case "save":
+        return ok(await save(sr, payload.customer));
+      case "delete":
+        return ok(await remove(sr, payload));
+      case "search": {
+        const { q, limit = 20, skip = 0, sort = "-created_date" } = payload;
+        let rows = await scanAll(sr.entities["commerce.Customer"], null, sort);
+        if (q) {
+          rows = rows.filter((c) =>
+            textMatch(c.email, q) || textMatch(c.username, q) ||
+            textMatch(`${c.first_name ?? ""} ${c.last_name ?? ""}`, q)
+          );
+        }
+        return ok(pageSlice(rows, Number(limit), Number(skip)));
+      }
+      case "invite":
+        return ok(await invite(base44, sr, payload));
+      case "recalculate-stats": {
+        const customer = await getCustomer(sr, payload.customer_id);
+        return ok(await recalcStats(sr, customer));
+      }
+      default:
+        return fail(400, `Unknown action: ${action}`, "unknown_action");
+    }
+  } catch (e) {
+    if (e instanceof HttpError) return fail(e.status, e.message, e.code);
+    console.error("commerce/admin-customers error:", e);
+    return fail(500, (e as Error).message ?? "Internal error");
+  }
+});
+
+async function getCustomer(sr: any, id: string): Promise<any> {
+  if (!id) throw new HttpError(400, "customer_id is required", "invalid_payload");
+  const customer = await sr.entities["commerce.Customer"].get(id);
+  if (!customer) throw new HttpError(404, "Customer not found", "not_found");
+  return customer;
+}
+
+async function save(sr: any, customer: any): Promise<any> {
+  if (!customer) throw new HttpError(400, "customer is required", "invalid_payload");
+  const email = String(customer.email ?? "").toLowerCase().trim();
+  if (!email) throw new HttpError(400, "Customer email is required.", "invalid_payload");
+
+  const dupes = (await sr.entities["commerce.Customer"].filter({ email }, undefined, 2)) ?? [];
+  if (dupes.some((c: any) => c.id !== customer.id)) {
+    throw new HttpError(409, `A customer with email "${email}" already exists.`, "duplicate_email");
+  }
+
+  const { id, created_date: _cd, updated_date: _ud, created_by: _cb, ...fields } = { ...customer, email };
+  let saved: any;
+  if (id) {
+    const prev = await getCustomer(sr, id);
+    await sr.entities["commerce.Customer"].update(id, fields);
+    saved = { ...prev, ...fields };
+    await dispatch(sr, "customer.updated", saved);
+  } else {
+    saved = await sr.entities["commerce.Customer"].create({
+      is_guest: fields.user_id ? false : (fields.is_guest ?? true),
+      orders_count: 0,
+      total_spent: 0,
+      is_paying_customer: false,
+      ...fields,
+    });
+    await dispatch(sr, "customer.created", saved);
+  }
+  return saved;
+}
+
+async function remove(sr: any, payload: any): Promise<any> {
+  const customer = await getCustomer(sr, payload.id);
+  if (payload.reassign_orders_to_guest !== false) {
+    const orders = await scanAll(sr.entities["commerce.Order"], { customer_id: customer.id }, "-created_date", { fields: ["id"] });
+    for (const o of orders) await sr.entities["commerce.Order"].update(o.id, { customer_id: "" });
+  }
+  await sr.entities["commerce.Customer"].delete(customer.id);
+  await dispatch(sr, "customer.deleted", customer);
+  return { deleted: customer.id };
+}
+
+/** Invite the customer to the app (creates/links a Base44 user, role "user"). */
+async function invite(base44: any, sr: any, payload: any): Promise<any> {
+  const customer = await getCustomer(sr, payload.customer_id);
+  try {
+    const result = await base44.users.inviteUser(customer.email, "user");
+    const userId = result?.id ?? result?.user_id ?? "";
+    if (userId) {
+      await sr.entities["commerce.Customer"].update(customer.id, { user_id: userId, is_guest: false });
+      customer.user_id = userId;
+      customer.is_guest = false;
+    }
+    return { invited: true, customer };
+  } catch (e) {
+    // invite may fail if the user already exists — surface but don't 500
+    return { invited: false, error: (e as Error).message, customer };
+  }
+}
+
+/**
+ * Recompute orders_count / total_spent / is_paying_customer.
+ * Counted spend = paid orders (date_paid set or processing/completed) minus
+ * their refunds; orders_count excludes cancelled/failed (standard commerce semantics).
+ */
+async function recalcStats(sr: any, customer: any): Promise<any> {
+  const orders = await scanAll(sr.entities["commerce.Order"], { customer_id: customer.id });
+  const counted = orders.filter((o) => !["cancelled", "failed"].includes(o.status));
+  const paid = orders.filter((o) => o.date_paid || ["processing", "completed"].includes(o.status));
+  const totalSpent = round2(paid.reduce(
+    (a, o) => a + (Number(o.total) || 0) - (Number(o.total_refunded) || 0),
+    0,
+  ));
+  const patch = {
+    orders_count: counted.length,
+    total_spent: totalSpent,
+    is_paying_customer: totalSpent > 0,
+  };
+  await sr.entities["commerce.Customer"].update(customer.id, patch);
+  return { ...customer, ...patch };
+}