@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 +19 -0
- package/LICENSE +21 -0
- package/README.md +70 -2
- package/dist/chunk-YD2SGV6Y.js +23 -0
- package/dist/chunk-YD2SGV6Y.js.map +1 -0
- package/dist/errors-D-I4iaTa.d.cts +18 -0
- package/dist/errors-D-I4iaTa.d.ts +18 -0
- package/dist/index.cjs +1290 -0
- package/dist/index.cjs.map +1 -0
- package/dist/index.d.cts +1018 -0
- package/dist/index.d.ts +1018 -0
- package/dist/index.js +1260 -0
- package/dist/index.js.map +1 -0
- package/dist/sellforge.global.js +3 -0
- package/dist/sellforge.global.js.map +1 -0
- package/dist/server.cjs +71 -0
- package/dist/server.cjs.map +1 -0
- package/dist/server.d.cts +61 -0
- package/dist/server.d.ts +61 -0
- package/dist/server.js +58 -0
- package/dist/server.js.map +1 -0
- package/package.json +77 -4
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
|
-
#
|
|
1
|
+
# @sellforge/storefront
|
|
2
2
|
|
|
3
|
-
|
|
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 };
|