@flintpay/node 0.3.0-beta.1 → 0.4.0-beta.1

package/RUNTIME.md

@@ -1,6 +1,6 @@
 # Flint Public API runtime guide (node)
 
-Package 0.3.0-beta.1; API 2026-09-07.
+Package 0.4.0-beta.1; API 2026-09-07.
 
 [Back to the quickstart](README.md) · [API reference](REFERENCE.md)
 
@@ -49,7 +49,7 @@ Portable digit/word pattern escapes retain their ASCII ECMAScript meaning in bot
 
 ## Retries and idempotency
 
-Retries count total attempts, include jitter and Retry-After, and never exceed the declared policy. Persist an idempotency key across process restarts and submissions within the server's documented retention/scope. Automatic keys cover one SDK call only. Explicit keys from operation inputs, request headers or idempotencyKey are preserved; conflicting values fail before dispatch. A timeout after dispatch can leave the remote outcome unknown; inspect SdkError.outcome. Disable nested transport/application retries to avoid multiplied attempts. 409/412 are distinct conflicts and never automatically overwritten.
+Retries count total attempts, include jitter and Retry-After, and never exceed the declared policy. Persist an idempotency key across process restarts and submissions within the server's documented retention/scope. Automatic keys cover one SDK call only and can satisfy required idempotency headers; generated keys must pass the declared header validation. Explicit keys from operation inputs, request headers or idempotencyKey are preserved; conflicting values fail before dispatch. A timeout after dispatch can leave the remote outcome unknown; inspect SdkError.outcome. Disable nested transport/application retries to avoid multiplied attempts. 409/412 are distinct conflicts and never automatically overwritten.
 
 ## Timeouts, streaming and cancellation
 
@@ -63,7 +63,7 @@ Pagination is lazy, supports maxPages/maxItems, and does not guarantee a stable
 
 ## Destinations and API versions
 
-Explicit allowedOrigins govern all destinations, including pagination. HTTPS is required unless allowInsecureHttp is set for local tests. Declared 302/307 responses return Location metadata without following redirects; undeclared redirects are rejected. Authentication is attached only after destination validation. API version headers are pinned when configured; changing them does not update generated types.
+Explicit allowedOrigins govern all destinations, including pagination. HTTPS is required unless allowInsecureHttp is set for local tests. Declared 302/307 responses return Location metadata without following redirects; undeclared redirects are rejected. Authentication is attached only after destination validation. API version headers are pinned when configured; changing them does not update generated types. Required version headers are supplied by the pin. Required conditional headers may be supplied through ifMatch or request headers without duplicating them in the input. Effective managed header values are validated before dispatch.
 
 ## Client lifecycle and transports
 

package/codec-plan.js

@@ -66,13 +66,16 @@ export function directionalSchema(schema, response) {
     collect(schema);
     if (!omitted.size)
         return schema;
+    // A directional field cannot satisfy a predicate in the opposite direction.
+    // Keep predicates intact so its absence makes the condition false; applied
+    // constraints still omit directionally unavailable required fields.
     const project = (s) => ({
         ...s,
         ...(s.required ? { required: s.required.filter((key) => !omitted.has(key)) } : {}),
         ...(s.allOf ? { allOf: s.allOf.map(project) } : {}),
         ...(s.anyOf ? { anyOf: s.anyOf.map(project) } : {}),
         ...(s.oneOf ? { oneOf: s.oneOf.map(project) } : {}),
-        ...(s.if ? { if: project(s.if) } : {}),
+        ...(s.if ? { if: s.if } : {}),
         ...(s.then ? { then: project(s.then) } : {}),
         ...(s.else ? { else: project(s.else) } : {}),
     });

package/examples/creditNotes-createRefund.mjs

@@ -0,0 +1,18 @@
+import { Client } from '@flintpay/node';
+const client = new Client({
+  baseUrl: process.env.API_BASE_URL ?? 'https://sandbox.example.invalid',
+  apiKey: process.env.API_KEY ?? '',
+});
+// Reuse this key when retrying the same action.
+const idempotencyKey = crypto.randomUUID();
+
+const result = await client.creditNotes.createRefund(
+  "example",
+  {
+    reason: "duplicate",
+    "Idempotency-Key": idempotencyKey,
+  },
+  { maxAttempts: 1 },
+);
+console.log(result.refund_id);
+console.log(result.status);

package/examples/creditNotes-createRefund.ts

@@ -0,0 +1,18 @@
+import { Client } from '@flintpay/node';
+const client = new Client({
+  baseUrl: process.env.API_BASE_URL ?? 'https://sandbox.example.invalid',
+  apiKey: process.env.API_KEY ?? '',
+});
+// Reuse this key when retrying the same action.
+const idempotencyKey = crypto.randomUUID();
+
+const result = await client.creditNotes.createRefund(
+  "example",
+  {
+    reason: "duplicate",
+    "Idempotency-Key": idempotencyKey,
+  },
+  { maxAttempts: 1 },
+);
+console.log(result.refund_id);
+console.log(result.status);

package/examples/creditNotes-listRefunds.mjs

@@ -0,0 +1,10 @@
+import { Client } from '@flintpay/node';
+const client = new Client({
+  baseUrl: process.env.API_BASE_URL ?? 'https://sandbox.example.invalid',
+  apiKey: process.env.API_KEY ?? '',
+});
+const result = await client.creditNotes.listRefunds(
+  "example",
+  {},
+  { maxAttempts: 1 },
+);

package/examples/creditNotes-listRefunds.ts

@@ -0,0 +1,10 @@
+import { Client } from '@flintpay/node';
+const client = new Client({
+  baseUrl: process.env.API_BASE_URL ?? 'https://sandbox.example.invalid',
+  apiKey: process.env.API_KEY ?? '',
+});
+const result = await client.creditNotes.listRefunds(
+  "example",
+  {},
+  { maxAttempts: 1 },
+);

package/examples/developer-getAuthContext.mjs

@@ -7,5 +7,4 @@ const result = await client.developer.getAuthContext(
   {},
   { maxAttempts: 1 },
 );
-console.log(result.api_key_id);
 console.log(result.merchant_id);

package/examples/developer-getAuthContext.ts

@@ -7,5 +7,4 @@ const result = await client.developer.getAuthContext(
   {},
   { maxAttempts: 1 },
 );
-console.log(result.api_key_id);
 console.log(result.merchant_id);

package/examples/invoices-assessLateFee.mjs

@@ -0,0 +1,17 @@
+import { Client } from '@flintpay/node';
+const client = new Client({
+  baseUrl: process.env.API_BASE_URL ?? 'https://sandbox.example.invalid',
+  apiKey: process.env.API_KEY ?? '',
+});
+// Reuse this key when retrying the same action.
+const idempotencyKey = crypto.randomUUID();
+
+const result = await client.invoices.assessLateFee(
+  "example",
+  {
+    "Idempotency-Key": idempotencyKey,
+  },
+  { maxAttempts: 1 },
+);
+console.log(result.invoice_id);
+console.log(result.merchant_id);

package/examples/invoices-assessLateFee.ts

@@ -0,0 +1,17 @@
+import { Client } from '@flintpay/node';
+const client = new Client({
+  baseUrl: process.env.API_BASE_URL ?? 'https://sandbox.example.invalid',
+  apiKey: process.env.API_KEY ?? '',
+});
+// Reuse this key when retrying the same action.
+const idempotencyKey = crypto.randomUUID();
+
+const result = await client.invoices.assessLateFee(
+  "example",
+  {
+    "Idempotency-Key": idempotencyKey,
+  },
+  { maxAttempts: 1 },
+);
+console.log(result.invoice_id);
+console.log(result.merchant_id);

package/examples/invoices-waiveLateFee.mjs

@@ -0,0 +1,19 @@
+import { Client } from '@flintpay/node';
+const client = new Client({
+  baseUrl: process.env.API_BASE_URL ?? 'https://sandbox.example.invalid',
+  apiKey: process.env.API_KEY ?? '',
+});
+// Reuse this key when retrying the same action.
+const idempotencyKey = crypto.randomUUID();
+
+const result = await client.invoices.waiveLateFee(
+  "example",
+  "example",
+  {
+    reason: "example",
+    "Idempotency-Key": idempotencyKey,
+  },
+  { maxAttempts: 1 },
+);
+console.log(result.invoice_id);
+console.log(result.merchant_id);

package/examples/invoices-waiveLateFee.ts

@@ -0,0 +1,19 @@
+import { Client } from '@flintpay/node';
+const client = new Client({
+  baseUrl: process.env.API_BASE_URL ?? 'https://sandbox.example.invalid',
+  apiKey: process.env.API_KEY ?? '',
+});
+// Reuse this key when retrying the same action.
+const idempotencyKey = crypto.randomUUID();
+
+const result = await client.invoices.waiveLateFee(
+  "example",
+  "example",
+  {
+    reason: "example",
+    "Idempotency-Key": idempotencyKey,
+  },
+  { maxAttempts: 1 },
+);
+console.log(result.invoice_id);
+console.log(result.merchant_id);

package/examples/oauth-exchangePartnerInstallToken.mjs

@@ -10,5 +10,3 @@ const result = await client.oauth.exchangePartnerInstallToken(
   },
   { maxAttempts: 1 },
 );
-console.log(result.environment_grant_id);
-console.log(result.merchant_id);

package/examples/oauth-exchangePartnerInstallToken.ts

@@ -10,5 +10,3 @@ const result = await client.oauth.exchangePartnerInstallToken(
   },
   { maxAttempts: 1 },
 );
-console.log(result.environment_grant_id);
-console.log(result.merchant_id);

package/guides/pagination-and-retries.md

@@ -1,4 +1,4 @@
-<!-- Package 0.3.0-beta.1; API 2026-09-07 -->
+<!-- Package 0.4.0-beta.1; API 2026-09-07 -->
 
 # Pagination and retries
 
@@ -40,7 +40,7 @@ Pagination can make multiple requests to fetch distinct pages; it does not autom
 
 ## Persist keys before writes
 
-Every write that declares `Idempotency-Key` in the pinned API contract supports `idempotencyKey` through request options (278 operations). Required-key endpoints accept the key here without duplicating it in the input; they still reject a missing key before dispatch. Supplying a key does not enable automatic retries. Pass `idempotencyKey` in request options, or the identical `Idempotency-Key` input/header. The SDK sends the supplied key and rejects conflicting key sources. Automatic key generation is disabled.
+Every write that declares `Idempotency-Key` in the pinned API contract supports `idempotencyKey` through request options (281 operations). Required-key endpoints accept the key here without duplicating it in the input; they still reject a missing key before dispatch. Supplying a key does not enable automatic retries. Pass `idempotencyKey` in request options, or the identical `Idempotency-Key` input/header. The SDK sends the supplied key and rejects conflicting key sources. Automatic key generation is disabled.
 
 Create and persist a key when your application decides on the business action. Reuse that saved key and the identical input when resuming after a crash or timeout. A different action or changed request needs a new key. Replay lifetime and semantics follow the endpoint contract. The general window is 24 hours; inventory command keys persist for at least as long as their inventory effects, and merchant account sessions mint fresh secrets on repeated success. Follow each endpoint's documented scope and retention. If the final outcome is unknown, reconcile the action before resubmitting. A deliberate retry must reuse the persisted key and identical request body.