@sellforge/storefront 0.0.0-stage → 1.0.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/CHANGELOG.md ADDED
@@ -0,0 +1,19 @@
1
+ # Changelog — @sellforge/storefront
2
+
3
+ Semantic versioning: new features → minor, fixes → patch. Breaking changes only in a new major version.
4
+
5
+ ## 1.0.0 - 18.11.2026
6
+
7
+ First release, built from scratch against the store API of Sellforge Commerce (Core 1.6.0).
8
+
9
+ - Two modes: publishable key (`pk_sf_…`, own domain and servers) and hosted online store (same-origin `/_sellforge`, no key)
10
+ - Catalog: products with client-side filters (category, brand, vehicle, stock, text), sorting and paging; server search with typo tolerance and facets; categories, brands, bundle deals, product JSON-LD and sitemap
11
+ - Vehicles: makes, models, model years, fitment check
12
+ - Cart: create, add (variants, options, customer inputs), add several, change, remove, discount codes, contact details and shipping method, change events
13
+ - Checkout: hosted checkout session from the cart, redirect, return-page result, order lookup, discount-code check, subscription plans and subscription checkout
14
+ - Customer account: register, login with two-factor step, password reset, email verification, profile, password, orders, invoices (PDF), addresses, subscriptions, GDPR export and deletion, guest order tracking
15
+ - Content: CMS pages, legal texts (rendered to safe HTML), Strapi entries, blog with SEO helper
16
+ - Shop: branding, languages with automatic selection, shipping methods and countries, newsletter signup, online withdrawal, Google Ads and Pinterest settings, Insights bridge and attribution headers
17
+ - Helpers: `html.escape/sanitize/markdown`, `format.price/date`, typed `SellforgeError`
18
+ - Server (`@sellforge/storefront/server`): webhook signature verification, typed webhook events, return-URL signature check (Web Crypto)
19
+ - Builds: ESM, CommonJS, TypeScript types, script-tag build (`window.Sellforge`)
package/LICENSE ADDED
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 Sellforge
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
package/README.md CHANGED
@@ -1,3 +1,71 @@
1
- # Temporary Holding Version
1
+ # @sellforge/storefront
2
2
 
3
- This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
3
+ The official SDK for building shops on **Sellforge Commerce**: catalog, search, cart, checkout,
4
+ customer accounts, content and webhooks — typed, dependency-free, for the browser, Node.js and edge runtimes.
5
+
6
+ 📖 Full documentation: **https://docs.sellforge.ai/sdk/introduction**
7
+
8
+ ```bash
9
+ npm install @sellforge/storefront
10
+ ```
11
+
12
+ ```ts
13
+ import { createStorefront } from "@sellforge/storefront";
14
+
15
+ // Your own domain: the shop's publishable key (Settings → Developers)
16
+ const sf = createStorefront({ publishableKey: "pk_sf_…" });
17
+
18
+ const { products } = await sf.catalog.products({ inStock: true, sort: "price_asc" });
19
+ const cart = await sf.cart.add(products[0].id, { quantity: 1 });
20
+ console.log(sf.format.price(cart.total_cents)); // "19,90 €"
21
+
22
+ await sf.checkout.start({ returnUrl: "https://shop.example.com/checkout/result" });
23
+ ```
24
+
25
+ Inside a Sellforge-hosted online store (`*.sellforge.shop` or a connected domain) no key is needed:
26
+
27
+ ```ts
28
+ const sf = createStorefront();
29
+ ```
30
+
31
+ Without a bundler:
32
+
33
+ ```html
34
+ <script src="https://cdn.jsdelivr.net/npm/@sellforge/storefront@1/dist/sellforge.global.js"></script>
35
+ <script>
36
+ const sf = Sellforge.createStorefront({ publishableKey: "pk_sf_…" });
37
+ </script>
38
+ ```
39
+
40
+ Verify webhooks on your server:
41
+
42
+ ```ts
43
+ import { constructWebhookEvent } from "@sellforge/storefront/server";
44
+
45
+ const event = await constructWebhookEvent(rawBody, req.headers["x-sellforge-signature"], process.env.SELLFORGE_WEBHOOK_SECRET!);
46
+ if (event.type === "checkout.completed") { /* fulfil event.data.order_id once */ }
47
+ ```
48
+
49
+ ## Modules
50
+
51
+ | Module | What it does |
52
+ | --- | --- |
53
+ | `catalog` | Products, server search with facets, categories, brands, bundle deals, JSON-LD, sitemap |
54
+ | `vehicles` | Makes, models, model years, fitment check |
55
+ | `cart` | Add, change, remove, discount codes, shipping details, change events |
56
+ | `checkout` | Hosted checkout session, redirect, result page, subscriptions |
57
+ | `account` | Register, login (2FA), password reset, orders, invoices, addresses, subscriptions, GDPR |
58
+ | `pages`, `legal`, `content`, `blog` | CMS pages, legal texts, Strapi entries, blog with SEO |
59
+ | `shop`, `shipping`, `newsletter`, `withdrawal`, `insights` | Branding, languages, shipping, signup, online withdrawal, analytics |
60
+ | `html`, `format` | Safe HTML, Markdown, price and date formatting |
61
+
62
+ ## Development
63
+
64
+ ```bash
65
+ npm ci
66
+ npm run typecheck && npm test && npm run build && npm run check:package
67
+ ```
68
+
69
+ A tag `vX.Y.Z` matching `package.json` publishes to npm through GitLab CI with npm trusted publishing (OIDC).
70
+
71
+ MIT License
@@ -0,0 +1,23 @@
1
+ var __defProp = Object.defineProperty;
2
+ var __export = (target, all) => {
3
+ for (var name in all)
4
+ __defProp(target, name, { get: all[name], enumerable: true });
5
+ };
6
+
7
+ // src/errors.ts
8
+ var SellforgeError = class extends Error {
9
+ constructor(status, message, code, details) {
10
+ super(message);
11
+ this.name = "SellforgeError";
12
+ this.status = status;
13
+ this.code = code ?? null;
14
+ this.details = details ?? null;
15
+ }
16
+ };
17
+ function isSellforgeError(value) {
18
+ return value instanceof SellforgeError || typeof value === "object" && value !== null && value.name === "SellforgeError";
19
+ }
20
+
21
+ export { SellforgeError, __export, isSellforgeError };
22
+ //# sourceMappingURL=chunk-YD2SGV6Y.js.map
23
+ //# sourceMappingURL=chunk-YD2SGV6Y.js.map
@@ -0,0 +1 @@
1
+ {"version":3,"sources":["../src/errors.ts"],"names":[],"mappings":";;;;;;;AAQO,IAAM,cAAA,GAAN,cAA6B,KAAA,CAAM;AAAA,EAMxC,WAAA,CAAY,MAAA,EAAgB,OAAA,EAAiB,IAAA,EAAsB,OAAA,EAAmB;AACpF,IAAA,KAAA,CAAM,OAAO,CAAA;AANf,IAAA,IAAA,CAAkB,IAAA,GAAO,gBAAA;AAOvB,IAAA,IAAA,CAAK,MAAA,GAAS,MAAA;AACd,IAAA,IAAA,CAAK,OAAO,IAAA,IAAQ,IAAA;AACpB,IAAA,IAAA,CAAK,UAAU,OAAA,IAAW,IAAA;AAAA,EAC5B;AACF;AAEO,SAAS,iBAAiB,KAAA,EAAyC;AACxE,EAAA,OAAO,KAAA,YAAiB,kBAAmB,OAAO,KAAA,KAAU,YAAY,KAAA,KAAU,IAAA,IAAS,MAA6B,IAAA,KAAS,gBAAA;AACnI","file":"chunk-YD2SGV6Y.js","sourcesContent":["/**\n * Every failed request rejects with a `SellforgeError`.\n *\n * `status` is the HTTP status (0 for network failures), `code` the machine-readable\n * code from the API when it sends one (for example `eingabe_fehlt`,\n * `return_url_not_allowed`), and `message` the API's human-readable message.\n * API messages are German by default; show them to shoppers or map `code` to your own text.\n */\nexport class SellforgeError extends Error {\n override readonly name = \"SellforgeError\";\n readonly status: number;\n readonly code: string | null;\n readonly details: unknown;\n\n constructor(status: number, message: string, code?: string | null, details?: unknown) {\n super(message);\n this.status = status;\n this.code = code ?? null;\n this.details = details ?? null;\n }\n}\n\nexport function isSellforgeError(value: unknown): value is SellforgeError {\n return value instanceof SellforgeError || (typeof value === \"object\" && value !== null && (value as { name?: unknown }).name === \"SellforgeError\");\n}\n"]}
@@ -0,0 +1,18 @@
1
+ /**
2
+ * Every failed request rejects with a `SellforgeError`.
3
+ *
4
+ * `status` is the HTTP status (0 for network failures), `code` the machine-readable
5
+ * code from the API when it sends one (for example `eingabe_fehlt`,
6
+ * `return_url_not_allowed`), and `message` the API's human-readable message.
7
+ * API messages are German by default; show them to shoppers or map `code` to your own text.
8
+ */
9
+ declare class SellforgeError extends Error {
10
+ readonly name = "SellforgeError";
11
+ readonly status: number;
12
+ readonly code: string | null;
13
+ readonly details: unknown;
14
+ constructor(status: number, message: string, code?: string | null, details?: unknown);
15
+ }
16
+ declare function isSellforgeError(value: unknown): value is SellforgeError;
17
+
18
+ export { SellforgeError as S, isSellforgeError as i };
@@ -0,0 +1,18 @@
1
+ /**
2
+ * Every failed request rejects with a `SellforgeError`.
3
+ *
4
+ * `status` is the HTTP status (0 for network failures), `code` the machine-readable
5
+ * code from the API when it sends one (for example `eingabe_fehlt`,
6
+ * `return_url_not_allowed`), and `message` the API's human-readable message.
7
+ * API messages are German by default; show them to shoppers or map `code` to your own text.
8
+ */
9
+ declare class SellforgeError extends Error {
10
+ readonly name = "SellforgeError";
11
+ readonly status: number;
12
+ readonly code: string | null;
13
+ readonly details: unknown;
14
+ constructor(status: number, message: string, code?: string | null, details?: unknown);
15
+ }
16
+ declare function isSellforgeError(value: unknown): value is SellforgeError;
17
+
18
+ export { SellforgeError as S, isSellforgeError as i };