@quickshops/sdk 1.0.3 → 1.0.4
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/README.md +151 -28
- package/package.json +1 -1
package/README.md
CHANGED
|
@@ -1,78 +1,201 @@
|
|
|
1
|
-
#
|
|
1
|
+
# @quickshops/sdk
|
|
2
2
|
|
|
3
|
-
|
|
4
|
-
|
|
5
|
-
This package is **closed source** and proprietary to QuickShops. Installing it grants you a license to use it with the QuickShops API; it is not open source and may not be redistributed or modified outside the terms of your QuickShops agreement.
|
|
3
|
+
Developer-friendly and type-safe TypeScript SDK for the *QuickShops Headless API*.
|
|
6
4
|
|
|
7
5
|
[](https://quickshops.app)
|
|
8
6
|
[](https://quickshops.app)
|
|
9
7
|
|
|
10
8
|
## Summary
|
|
11
9
|
|
|
12
|
-
QuickShops Headless API for starter templates and
|
|
10
|
+
QuickShops Headless API for starter templates and custom storefronts. Use this SDK server-side to fetch products, manage carts, start checkout, and handle subscriptions.
|
|
11
|
+
|
|
12
|
+
This package is **closed source** and proprietary to QuickShops. Full docs: [docs.quickshops.app](https://docs.quickshops.app/sdk/installation).
|
|
13
13
|
|
|
14
|
-
|
|
14
|
+
## Table of Contents
|
|
15
|
+
|
|
16
|
+
- [@quickshops/sdk](#quickshops-sdk)
|
|
17
|
+
- [Summary](#summary)
|
|
18
|
+
- [Table of Contents](#table-of-contents)
|
|
19
|
+
- [SDK Installation](#sdk-installation)
|
|
20
|
+
- [Requirements](#requirements)
|
|
21
|
+
- [SDK Example Usage](#sdk-example-usage)
|
|
22
|
+
- [Authentication](#authentication)
|
|
23
|
+
- [Available Resources and Operations](#available-resources-and-operations)
|
|
24
|
+
- [Error Handling](#error-handling)
|
|
25
|
+
- [Development](#development)
|
|
26
|
+
- [Maturity](#maturity)
|
|
27
|
+
- [License](#license)
|
|
15
28
|
|
|
16
29
|
## SDK Installation
|
|
17
30
|
|
|
31
|
+
The SDK can be installed with [npm](https://www.npmjs.com/), [pnpm](https://pnpm.io/), [bun](https://bun.sh/), or [yarn](https://classic.yarnpkg.com/en/).
|
|
32
|
+
|
|
33
|
+
### NPM
|
|
34
|
+
|
|
18
35
|
```bash
|
|
19
36
|
npm add @quickshops/sdk
|
|
20
37
|
```
|
|
21
38
|
|
|
39
|
+
### PNPM
|
|
40
|
+
|
|
22
41
|
```bash
|
|
23
42
|
pnpm add @quickshops/sdk
|
|
24
43
|
```
|
|
25
44
|
|
|
26
|
-
|
|
45
|
+
### Bun
|
|
46
|
+
|
|
47
|
+
```bash
|
|
48
|
+
bun add @quickshops/sdk
|
|
49
|
+
```
|
|
50
|
+
|
|
51
|
+
### Yarn
|
|
52
|
+
|
|
53
|
+
```bash
|
|
54
|
+
yarn add @quickshops/sdk
|
|
55
|
+
```
|
|
56
|
+
|
|
57
|
+
> [!NOTE]
|
|
58
|
+
> This package is published as an ES Module (ESM) only. For CommonJS apps, use `await import("@quickshops/sdk")`.
|
|
59
|
+
|
|
60
|
+
## Requirements
|
|
61
|
+
|
|
62
|
+
For supported JavaScript runtimes, see [RUNTIMES.md](RUNTIMES.md).
|
|
27
63
|
|
|
28
64
|
## SDK Example Usage
|
|
29
65
|
|
|
66
|
+
### Example
|
|
67
|
+
|
|
30
68
|
```typescript
|
|
31
69
|
import { Quickshops } from "@quickshops/sdk";
|
|
32
70
|
|
|
33
|
-
const
|
|
71
|
+
const qs = new Quickshops({
|
|
34
72
|
serverURL: "https://api.quickshops.app",
|
|
35
73
|
bearerAuth: process.env.HEADLESS_API_KEY!,
|
|
36
74
|
});
|
|
37
75
|
|
|
38
|
-
|
|
76
|
+
async function run() {
|
|
77
|
+
const { data: products } = await qs.products.productsGetAll();
|
|
78
|
+
console.log(products);
|
|
79
|
+
}
|
|
80
|
+
|
|
81
|
+
run();
|
|
39
82
|
```
|
|
40
83
|
|
|
41
|
-
Use the SDK in server-only code. Never expose your API key to the browser.
|
|
84
|
+
Use the SDK in server-only code (API routes, server actions, loaders). Never expose your API key to the browser.
|
|
42
85
|
|
|
43
86
|
## Authentication
|
|
44
87
|
|
|
45
|
-
|
|
88
|
+
### Per-Client Security Schemes
|
|
89
|
+
|
|
90
|
+
This SDK supports the following security scheme globally:
|
|
91
|
+
|
|
92
|
+
| Name | Type | Scheme | Environment Variable |
|
|
93
|
+
| --- | --- | --- | --- |
|
|
94
|
+
| `bearerAuth` | http | HTTP Bearer | `QUICKSHOPS_BEARER_AUTH` |
|
|
95
|
+
|
|
96
|
+
Set `bearerAuth` when creating the client. API keys start with `qk_` and are sent as `Authorization: Bearer qk_...`.
|
|
97
|
+
|
|
98
|
+
```typescript
|
|
99
|
+
import { Quickshops } from "@quickshops/sdk";
|
|
100
|
+
|
|
101
|
+
const qs = new Quickshops({
|
|
102
|
+
serverURL: "https://api.quickshops.app",
|
|
103
|
+
bearerAuth: process.env.HEADLESS_API_KEY!,
|
|
104
|
+
});
|
|
105
|
+
|
|
106
|
+
const { data: store } = await qs.store.storeGet();
|
|
107
|
+
```
|
|
108
|
+
|
|
109
|
+
The API base URL is `https://api.quickshops.app` (the SDK adds `/v1` to each path).
|
|
110
|
+
|
|
111
|
+
## Available Resources and Operations
|
|
112
|
+
|
|
113
|
+
<details open>
|
|
114
|
+
<summary>Available methods</summary>
|
|
115
|
+
|
|
116
|
+
### [Store](https://docs.quickshops.app/api/products)
|
|
117
|
+
|
|
118
|
+
* `storeGet` — Get store for API key
|
|
119
|
+
|
|
120
|
+
### [Products](https://docs.quickshops.app/api/products)
|
|
121
|
+
|
|
122
|
+
* `productsGetAll` — List products
|
|
123
|
+
* `productsGetById` — Get product
|
|
124
|
+
|
|
125
|
+
### [Cart](https://docs.quickshops.app/api/cart)
|
|
126
|
+
|
|
127
|
+
* `cartCreate` — Create cart
|
|
128
|
+
* `cartGet` — Get cart
|
|
129
|
+
* `cartAddLine` — Add cart line
|
|
130
|
+
* `cartUpdateLine` — Update cart line quantity
|
|
131
|
+
* `cartRemoveLine` — Remove cart line
|
|
132
|
+
* `cartClear` — Clear cart
|
|
133
|
+
|
|
134
|
+
### [Checkout](https://docs.quickshops.app/api/checkout)
|
|
135
|
+
|
|
136
|
+
* `checkoutCreateSession` — Create checkout session
|
|
137
|
+
|
|
138
|
+
### [Subscription](https://docs.quickshops.app/api/subscriptions)
|
|
46
139
|
|
|
47
|
-
|
|
140
|
+
* `subscriptionCreatePortalSession` — Create subscription portal session
|
|
48
141
|
|
|
49
|
-
|
|
50
|
-
| --- | --- |
|
|
51
|
-
| Products | [docs.quickshops.app/api/products](https://docs.quickshops.app/api/products) |
|
|
52
|
-
| Cart | [docs.quickshops.app/api/cart](https://docs.quickshops.app/api/cart) |
|
|
53
|
-
| Checkout | [docs.quickshops.app/api/checkout](https://docs.quickshops.app/api/checkout) |
|
|
54
|
-
| Subscriptions | [docs.quickshops.app/api/subscriptions](https://docs.quickshops.app/api/subscriptions) |
|
|
142
|
+
### [Health](https://docs.quickshops.app/api/overview)
|
|
55
143
|
|
|
56
|
-
|
|
144
|
+
* `healthCheck` — Health check
|
|
57
145
|
|
|
58
|
-
|
|
146
|
+
</details>
|
|
147
|
+
|
|
148
|
+
Method reference with request shapes: [docs.quickshops.app/sdk/installation](https://docs.quickshops.app/sdk/installation#method-reference).
|
|
149
|
+
|
|
150
|
+
## Error Handling
|
|
151
|
+
|
|
152
|
+
[`QuickshopsError`](https://docs.quickshops.app/sdk/error-handling) is the base class for HTTP error responses.
|
|
153
|
+
|
|
154
|
+
| Property | Type | Description |
|
|
155
|
+
| --- | --- | --- |
|
|
156
|
+
| `error.message` | `string` | Error message |
|
|
157
|
+
| `error.statusCode` | `number` | HTTP status code, e.g. `404` |
|
|
158
|
+
| `error.headers` | `Headers` | Response headers |
|
|
159
|
+
| `error.body` | `string` | Response body |
|
|
160
|
+
| `error.rawResponse` | `Response` | Raw HTTP response |
|
|
161
|
+
| `error.data$` | `object` | Optional structured error payload |
|
|
162
|
+
|
|
163
|
+
### Example
|
|
164
|
+
|
|
165
|
+
```typescript
|
|
166
|
+
import { Quickshops } from "@quickshops/sdk";
|
|
167
|
+
import * as errors from "@quickshops/sdk/models/errors";
|
|
168
|
+
|
|
169
|
+
const qs = new Quickshops({
|
|
170
|
+
serverURL: "https://api.quickshops.app",
|
|
171
|
+
bearerAuth: process.env.HEADLESS_API_KEY!,
|
|
172
|
+
});
|
|
173
|
+
|
|
174
|
+
try {
|
|
175
|
+
await qs.products.productsGetById({ productId: "prod_123" });
|
|
176
|
+
} catch (error) {
|
|
177
|
+
if (error instanceof errors.QuickshopsError) {
|
|
178
|
+
console.log(error.statusCode, error.message);
|
|
179
|
+
}
|
|
180
|
+
}
|
|
181
|
+
```
|
|
59
182
|
|
|
60
|
-
|
|
183
|
+
See [error handling](https://docs.quickshops.app/sdk/error-handling) for typed errors and retries.
|
|
61
184
|
|
|
62
|
-
|
|
185
|
+
# Development
|
|
63
186
|
|
|
64
|
-
|
|
187
|
+
## Maturity
|
|
65
188
|
|
|
66
|
-
This SDK is in beta. Pin a specific package version in production.
|
|
189
|
+
This SDK is in beta. There may be breaking changes between minor versions. Pin a specific package version in production.
|
|
67
190
|
|
|
68
|
-
|
|
191
|
+
## License
|
|
69
192
|
|
|
70
193
|
`@quickshops/sdk` is closed source software owned by QuickShops. All rights reserved.
|
|
71
194
|
|
|
72
|
-
You may install and use this SDK only to build applications that integrate with QuickShops. You may not copy, modify, sublicense, or redistribute the SDK except as
|
|
195
|
+
You may install and use this SDK only to build applications that integrate with QuickShops. You may not copy, modify, sublicense, or redistribute the SDK except as permitted by QuickShops.
|
|
73
196
|
|
|
74
|
-
|
|
197
|
+
Questions: [quickshops.app](https://quickshops.app)
|
|
75
198
|
|
|
76
199
|
### Made by QuickShops
|
|
77
200
|
|
|
78
|
-
Published and maintained by [QuickShops](https://quickshops.app).
|
|
201
|
+
Published and maintained by [QuickShops](https://quickshops.app).
|