@klingis/sdk 0.5.0 → 0.6.0

package/README.md

@@ -12,7 +12,7 @@ npm install @klingis/sdk
 
 ## Quickstart
 
-You need a Kling API key. Test keys (`sk_test_...`) are available right away from [kling.is/dashboard/api-keys](https://kling.is/dashboard/api-keys), or run `npx @klingis/cli init` and it writes `KLING_SECRET_KEY` to `.env.local` for you. Keep the key on your server; never ship it to the browser.
+You need a Kling API key. Test keys (`sk_test_...`) are available right away from [kling.is/dashboard/api-keys](https://kling.is/dashboard/api-keys), or run `npx @klingis/cli init` and it writes `KLING_SECRET_KEY` to `.env.local` for you. If your account can already take live payments, `init` writes a live key (`sk_live_...`): check the prefix before you develop against it. Keep the key on your server; never ship it to the browser.
 
 ```typescript
 import { configure, postV1CheckoutSessions } from "@klingis/sdk";
@@ -20,15 +20,22 @@ import { configure, postV1CheckoutSessions } from "@klingis/sdk";
 // Once, at startup
 configure({
   baseUrl: "https://api.kling.is",
-  headers: { Authorization: `Bearer ${process.env.KLING_SECRET_KEY}` },
+  headers: {
+    Authorization: `Bearer ${process.env.KLING_SECRET_KEY}`,
+    "Content-Type": "application/json", // required, see below
+  },
 });
 
 // Create a checkout session for 5.000 kr.
-const res = await postV1CheckoutSessions({
-  amount: 5000, // ISK has no decimals: 5000 means 5.000 kr.
-  currency: "ISK",
-  success_url: "https://example.is/thanks",
-});
+const res = await postV1CheckoutSessions(
+  {
+    amount: 5000, // ISK has no decimals: 5000 means 5.000 kr.
+    currency: "ISK",
+    success_url: "https://example.is/thanks",
+  },
+  // Optional: makes a retry safe (same key, same body, same response)
+  { headers: { "Idempotency-Key": "order-1042" } },
+);
 
 if (res.status === 200) {
   // Send the customer to res.data.url, or open the overlay in the
@@ -39,7 +46,9 @@ if (res.status === 200) {
 }
 ```
 
-Every function returns `{ data, status, headers }`. Check `status` before reading `data`. Error responses have the shape `{ error: { type, message, code } }`, where `code` is a descriptive string such as `card_declined_insufficient_funds`.
+Keep the `Content-Type` header in `configure`. This version of the SDK does not send it by itself, and without it the API ignores the request body: a checkout fails with a 400, a PATCH changes nothing, and a partial refund (`amount`) refunds the full amount.
+
+Every function returns `{ data, status, headers }`. Check `status` before reading `data`. Error responses have the shape `{ error: { type, message, code } }`, where `code` is a descriptive string such as `invalid_cursor`. A declined card is not an error response: `postV1PaymentIntents` returns 200 with `data.status` set to `"failed"` and the reason in `data.error.code` (for example `card_declined_insufficient_funds`). The money is taken only when `data.status` is `"captured"`.
 
 Function names follow the HTTP method and path: `POST /v1/checkout/sessions` is `postV1CheckoutSessions`, `GET /v1/customers/{id}` is `getV1CustomersById`, and so on. Your editor's autocomplete on the `@klingis/sdk` import lists them all.
 

package/dist/generated/events/events.d.ts

@@ -17,7 +17,7 @@ export type getV1EventsResponseSuccess = (getV1EventsResponse200) & {
 export type getV1EventsResponse = (getV1EventsResponseSuccess);
 export declare const getGetV1EventsUrl: (params: GetV1EventsParams) => string;
 /**
- * List events from the event ledger. Use the 'after' parameter to poll for new events since a given timestamp.
+ * List events from the event ledger. Use the 'after' parameter to poll for new events since a given timestamp. An event is stamped when it is written and becomes visible when its transaction commits, so polling with 'after' is best-effort: overlap your window by a few seconds and dedupe by event id.
  * @summary List recent events
  */
 export declare const getV1Events: (params: GetV1EventsParams, options?: Parameters<typeof customFetch>[1]) => Promise<getV1EventsResponse>;

package/dist/generated/events/events.js

@@ -11,7 +11,7 @@ export const getGetV1EventsUrl = (params) => {
     return stringifiedParams.length > 0 ? `http://localhost:3001/v1/events?${stringifiedParams}` : `http://localhost:3001/v1/events`;
 };
 /**
- * List events from the event ledger. Use the 'after' parameter to poll for new events since a given timestamp.
+ * List events from the event ledger. Use the 'after' parameter to poll for new events since a given timestamp. An event is stamped when it is written and becomes visible when its transaction commits, so polling with 'after' is best-effort: overlap your window by a few seconds and dedupe by event id.
  * @summary List recent events
  */
 export const getV1Events = async (params, options) => {