@paygentic/sdk 0.10.1 → 0.10.3

package/src/models/costreportresponse.ts

@@ -23,8 +23,17 @@ export type CostReportResponseObject = ClosedEnum<
   typeof CostReportResponseObject
 >;
 
+/**
+ * The read window, as requested: the report counts from <= t < to. Unlike `costRange`, `to` is not an instant the report covers, so a chart axis ends before it.
+ */
 export type Period = {
+  /**
+   * Start of the read window, included.
+   */
   from: Date;
+  /**
+   * End of the read window, excluded.
+   */
   to: Date;
 };
 
@@ -35,7 +44,7 @@ export type Pagination = {
 };
 
 /**
- * Where the caller's cost data actually lies in time. Present only when the selected range returned no cost. An object carries the bounds of the real cost events; null means the caller has no cost event at any time; an absent field means the extent was not resolved, because the result was not empty, because the lookup failed, or because the metering service does not serve the bounds method. An absent field must never be read as an absence.
+ * Where the caller's cost data actually lies in time. Present only when the selected range returned no cost. An object carries the bounds of the real cost events; null means the caller has no cost event at any time; an absent field means the extent was not resolved, because the result was not empty, because the lookup failed, or because the metering service does not serve the bounds method. An absent field must never be read as an absence. The bounds are instants that exist and both are included, so a window that holds `to` ends after it.
  */
 export type CostReportResponseCostRange = {
   /**
@@ -54,6 +63,9 @@ export type CostReportResponse = {
    * ISO 4217 currency code for all monetary values in this response.
    */
   currency: string;
+  /**
+   * The read window, as requested: the report counts from <= t < to. Unlike `costRange`, `to` is not an instant the report covers, so a chart axis ends before it.
+   */
   period: Period;
   /**
    * The active grouping dimension (e.g. 'cost', 'customer', or a dynamic dimension key).
@@ -93,7 +105,7 @@ export type CostReportResponse = {
    */
   emptyGroupCount?: number | null | undefined;
   /**
-   * Where the caller's cost data actually lies in time. Present only when the selected range returned no cost. An object carries the bounds of the real cost events; null means the caller has no cost event at any time; an absent field means the extent was not resolved, because the result was not empty, because the lookup failed, or because the metering service does not serve the bounds method. An absent field must never be read as an absence.
+   * Where the caller's cost data actually lies in time. Present only when the selected range returned no cost. An object carries the bounds of the real cost events; null means the caller has no cost event at any time; an absent field means the extent was not resolved, because the result was not empty, because the lookup failed, or because the metering service does not serve the bounds method. An absent field must never be read as an absence. The bounds are instants that exist and both are included, so a window that holds `to` ends after it.
    */
   costRange?: CostReportResponseCostRange | null | undefined;
 };

package/src/models/operations/getcostreport.ts

@@ -50,11 +50,11 @@ export type GetCostReportRequest = {
    */
   merchantId?: string | undefined;
   /**
-   * Start of the query window (ISO 8601).
+   * Start of the query window, included (ISO 8601).
    */
   from: Date;
   /**
-   * End of the query window (ISO 8601).
+   * End of the query window, excluded: the read counts from <= t < to (ISO 8601).
    */
   to: Date;
   /**

package/src/models/operations/getcostsummary.ts

@@ -28,11 +28,11 @@ export type GetCostSummaryRequest = {
    */
   subject?: string | undefined;
   /**
-   * Start of the query window (ISO 8601). Required together with 'to'.
+   * Start of the query window, included (ISO 8601). Required together with 'to'.
    */
   from: Date;
   /**
-   * End of the query window (ISO 8601). Required together with 'from'.
+   * End of the query window, excluded: the read counts from <= t < to (ISO 8601). Required together with 'from'.
    */
   to: Date;
   /**

package/src/models/operations/getprofitability.ts

@@ -10,11 +10,11 @@ export type GetProfitabilityRequest = {
    */
   merchantId: string;
   /**
-   * Start of the time range (ISO 8601 format)
+   * Start of the read window, included (ISO 8601 format)
    */
   from: Date;
   /**
-   * End of the time range (ISO 8601 format)
+   * End of the read window, excluded: the read counts from <= t < to, so a month ends at the first instant of the next month (ISO 8601 format)
    */
   to: Date;
   /**

package/src/models/operations/getrevenue.ts

@@ -45,11 +45,11 @@ export type PeriodBasis = ClosedEnum<typeof PeriodBasis>;
 
 export type GetRevenueRequest = {
   /**
-   * Start of the time range (ISO 8601 format)
+   * Start of the read window, included (ISO 8601 format)
    */
   startTime: Date;
   /**
-   * End of the time range (ISO 8601 format)
+   * End of the read window, excluded: the read counts startTime <= t < endTime, so a month ends at the first instant of the next month (ISO 8601 format)
    */
   endTime: Date;
   /**

package/src/models/operations/ingestevent.ts

@@ -6,7 +6,7 @@ import * as z from "zod/v3";
 
 export type IngestEventRequestBody2 = {
   /**
-   * CloudEvents type. Must match an eventType configured on a BillableMetric.
+   * CloudEvents type. Must match an eventType configured on a BillableMetric. Must not contain control characters.
    */
   type: string;
   /**
@@ -18,7 +18,7 @@ export type IngestEventRequestBody2 = {
    */
   subject?: string | undefined;
   /**
-   * Your own customer identifier, matched against the customer's externalId. Fallback for when the Paygentic customer ID is not known — prefer subject when it is. Events reported before the customer exists are linked retroactively once a customer with this externalId is created. Resolution is eventually consistent: after an externalId is removed or reassigned, events may resolve to the previous customer for up to one hour. If subject is also provided, subject takes precedence and externalSubject is recorded but not used for resolution.
+   * Your own customer identifier, matched against the customer's externalId. Fallback for when the Paygentic customer ID is not known — prefer subject when it is. Events reported before the customer exists are linked retroactively once a customer with this externalId is created. Resolution is eventually consistent: after an externalId is removed or reassigned, or its customer is deleted, events may resolve to the previous customer for up to one hour, and for up to 48 hours if Paygentic's database is unavailable. If subject is also provided, subject takes precedence and externalSubject is recorded but not used for resolution.
    */
   externalSubject: string;
   /**
@@ -45,7 +45,7 @@ export type IngestEventRequestBody2 = {
 
 export type IngestEventRequestBody1 = {
   /**
-   * CloudEvents type. Must match an eventType configured on a BillableMetric.
+   * CloudEvents type. Must match an eventType configured on a BillableMetric. Must not contain control characters.
    */
   type: string;
   /**
@@ -57,7 +57,7 @@ export type IngestEventRequestBody1 = {
    */
   subject: string;
   /**
-   * Your own customer identifier, matched against the customer's externalId. Fallback for when the Paygentic customer ID is not known — prefer subject when it is. Events reported before the customer exists are linked retroactively once a customer with this externalId is created. Resolution is eventually consistent: after an externalId is removed or reassigned, events may resolve to the previous customer for up to one hour. If subject is also provided, subject takes precedence and externalSubject is recorded but not used for resolution.
+   * Your own customer identifier, matched against the customer's externalId. Fallback for when the Paygentic customer ID is not known — prefer subject when it is. Events reported before the customer exists are linked retroactively once a customer with this externalId is created. Resolution is eventually consistent: after an externalId is removed or reassigned, or its customer is deleted, events may resolve to the previous customer for up to one hour, and for up to 48 hours if Paygentic's database is unavailable. If subject is also provided, subject takes precedence and externalSubject is recorded but not used for resolution.
    */
   externalSubject?: string | undefined;
   /**

package/src/models/operations/listentitlements.ts

@@ -53,6 +53,16 @@ export const ListEntitlementsObject = {
 } as const;
 export type ListEntitlementsObject = ClosedEnum<typeof ListEntitlementsObject>;
 
+/**
+ * Present only when the database can't be reached, or the list takes more than a second to compute. The response is then the last result for this same request in the past hour, computed at `computedAt`.
+ */
+export type Stale = {
+  /**
+   * When this result was computed.
+   */
+  computedAt: Date;
+};
+
 /**
  * Successfully retrieved the list of entitlements for the customer.
  */
@@ -66,6 +76,10 @@ export type ListEntitlementsResponse = {
    * Offset-based pagination response.
    */
   pagination: models.OffsetPagination;
+  /**
+   * Present only when the database can't be reached, or the list takes more than a second to compute. The response is then the last result for this same request in the past hour, computed at `computedAt`.
+   */
+  stale?: Stale | undefined;
 };
 
 /** @internal */
@@ -111,6 +125,24 @@ export const ListEntitlementsObject$inboundSchema: z.ZodNativeEnum<
   typeof ListEntitlementsObject
 > = z.nativeEnum(ListEntitlementsObject);
 
+/** @internal */
+export const Stale$inboundSchema: z.ZodType<Stale, z.ZodTypeDef, unknown> = z
+  .object({
+    computedAt: z.string().datetime({ offset: true }).transform(v =>
+      new Date(v)
+    ),
+  });
+
+export function staleFromJSON(
+  jsonString: string,
+): SafeParseResult<Stale, SDKValidationError> {
+  return safeParse(
+    jsonString,
+    (x) => Stale$inboundSchema.parse(JSON.parse(x)),
+    `Failed to parse 'Stale' from JSON`,
+  );
+}
+
 /** @internal */
 export const ListEntitlementsResponse$inboundSchema: z.ZodType<
   ListEntitlementsResponse,
@@ -120,6 +152,7 @@ export const ListEntitlementsResponse$inboundSchema: z.ZodType<
   object: ListEntitlementsObject$inboundSchema.default("list"),
   data: z.array(models.EntitlementListItem$inboundSchema),
   pagination: models.OffsetPagination$inboundSchema,
+  stale: z.lazy(() => Stale$inboundSchema).optional(),
 });
 
 export function listEntitlementsResponseFromJSON(

package/src/models/profitabilitysummaryresponse.ts

@@ -12,7 +12,7 @@ import {
 } from "./profitabilityrow.js";
 
 /**
- * Where the caller's revenue actually lies in time. Scoped by the same filters as the request (merchant, and where given customer, subscription and currency), so it is not an account-wide statement. Present only when the selected range returned nothing. An object carries the bounds of the real revenue; null means no revenue under these filters at any time; an absent field means the extent was not resolved, because the result was not empty or because the lookup failed. An absent field must never be read as an absence. The bounds may span more than this endpoint's maximum queryable range, so clamp before re-querying.
+ * Where the caller's revenue actually lies in time. Scoped by the same filters as the request (merchant, and where given customer, subscription and currency), so it is not an account-wide statement. Present only when the selected range returned nothing. An object carries the bounds of the real revenue; null means no revenue under these filters at any time; an absent field means the extent was not resolved, because the result was not empty or because the lookup failed. An absent field must never be read as an absence. The bounds are instants that exist and both are included, so a window that holds `to` ends after it. The bounds may span more than this endpoint's maximum queryable range, so clamp before re-querying.
  */
 export type ProfitabilitySummaryResponseRevenueRange = {
   /**
@@ -26,7 +26,7 @@ export type ProfitabilitySummaryResponseRevenueRange = {
 };
 
 /**
- * Where the caller's cost data actually lies in time. Present only when the selected range returned no cost. An object carries the bounds of the real cost events; null means the caller has no cost event at any time; an absent field means the extent was not resolved, because the result was not empty, because the lookup failed, or because the metering service does not serve the bounds method. An absent field must never be read as an absence.
+ * Where the caller's cost data actually lies in time. Present only when the selected range returned no cost. An object carries the bounds of the real cost events; null means the caller has no cost event at any time; an absent field means the extent was not resolved, because the result was not empty, because the lookup failed, or because the metering service does not serve the bounds method. An absent field must never be read as an absence. The bounds are instants that exist and both are included, so a window that holds `to` ends after it.
  */
 export type ProfitabilitySummaryResponseCostRange = {
   /**
@@ -73,11 +73,11 @@ export type ProfitabilitySummaryResponse = {
    */
   warnings?: Array<string> | undefined;
   /**
-   * Where the caller's revenue actually lies in time. Scoped by the same filters as the request (merchant, and where given customer, subscription and currency), so it is not an account-wide statement. Present only when the selected range returned nothing. An object carries the bounds of the real revenue; null means no revenue under these filters at any time; an absent field means the extent was not resolved, because the result was not empty or because the lookup failed. An absent field must never be read as an absence. The bounds may span more than this endpoint's maximum queryable range, so clamp before re-querying.
+   * Where the caller's revenue actually lies in time. Scoped by the same filters as the request (merchant, and where given customer, subscription and currency), so it is not an account-wide statement. Present only when the selected range returned nothing. An object carries the bounds of the real revenue; null means no revenue under these filters at any time; an absent field means the extent was not resolved, because the result was not empty or because the lookup failed. An absent field must never be read as an absence. The bounds are instants that exist and both are included, so a window that holds `to` ends after it. The bounds may span more than this endpoint's maximum queryable range, so clamp before re-querying.
    */
   revenueRange?: ProfitabilitySummaryResponseRevenueRange | null | undefined;
   /**
-   * Where the caller's cost data actually lies in time. Present only when the selected range returned no cost. An object carries the bounds of the real cost events; null means the caller has no cost event at any time; an absent field means the extent was not resolved, because the result was not empty, because the lookup failed, or because the metering service does not serve the bounds method. An absent field must never be read as an absence.
+   * Where the caller's cost data actually lies in time. Present only when the selected range returned no cost. An object carries the bounds of the real cost events; null means the caller has no cost event at any time; an absent field means the extent was not resolved, because the result was not empty, because the lookup failed, or because the metering service does not serve the bounds method. An absent field must never be read as an absence. The bounds are instants that exist and both are included, so a window that holds `to` ends after it.
    */
   costRange?: ProfitabilitySummaryResponseCostRange | null | undefined;
 };

package/src/models/revenuesummaryresponse.ts

@@ -28,7 +28,7 @@ import {
 } from "./revenuetrendbucket.js";
 
 /**
- * Where the caller's revenue actually lies in time. Scoped by the same filters as the request (merchant, and where given customer, subscription and currency), so it is not an account-wide statement. Present only when the selected range returned nothing. An object carries the bounds of the real revenue; null means no revenue under these filters at any time; an absent field means the extent was not resolved, because the result was not empty or because the lookup failed. An absent field must never be read as an absence. The bounds may span more than this endpoint's maximum queryable range, so clamp before re-querying.
+ * Where the caller's revenue actually lies in time. Scoped by the same filters as the request (merchant, and where given customer, subscription and currency), so it is not an account-wide statement. Present only when the selected range returned nothing. An object carries the bounds of the real revenue; null means no revenue under these filters at any time; an absent field means the extent was not resolved, because the result was not empty or because the lookup failed. An absent field must never be read as an absence. The bounds are instants that exist and both are included, so a window that holds `to` ends after it. The bounds may span more than this endpoint's maximum queryable range, so clamp before re-querying.
  */
 export type RevenueSummaryResponseRevenueRange = {
   /**
@@ -85,7 +85,7 @@ export type RevenueSummaryResponse = {
    */
   currencyBreakdown?: Array<CurrencyBreakdownEntry> | undefined;
   /**
-   * Where the caller's revenue actually lies in time. Scoped by the same filters as the request (merchant, and where given customer, subscription and currency), so it is not an account-wide statement. Present only when the selected range returned nothing. An object carries the bounds of the real revenue; null means no revenue under these filters at any time; an absent field means the extent was not resolved, because the result was not empty or because the lookup failed. An absent field must never be read as an absence. The bounds may span more than this endpoint's maximum queryable range, so clamp before re-querying.
+   * Where the caller's revenue actually lies in time. Scoped by the same filters as the request (merchant, and where given customer, subscription and currency), so it is not an account-wide statement. Present only when the selected range returned nothing. An object carries the bounds of the real revenue; null means no revenue under these filters at any time; an absent field means the extent was not resolved, because the result was not empty or because the lookup failed. An absent field must never be read as an absence. The bounds are instants that exist and both are included, so a window that holds `to` ends after it. The bounds may span more than this endpoint's maximum queryable range, so clamp before re-querying.
    */
   revenueRange?: RevenueSummaryResponseRevenueRange | null | undefined;
 };

package/src/sdk/invoicesv2.ts

@@ -148,7 +148,7 @@ export class InvoicesV2 extends ClientSDK {
    * - `hosted_link`: create a new hosted payment link and email it to the customer. The invoice stays unpaid until the customer pays on the link. Each call replaces the previous link. A payment link expires after 30 days; to collect an invoice whose link has expired, call this method again.
    * - `out_of_band`: record a payment that you collected outside Paygentic. The invoice changes to `PAID` immediately. A second call returns 409.
    *
-   * For `hosted_link`, an invoice that does not exist returns 403, the same as an invoice of another merchant.
+   * For `hosted_link`, an invoice that does not exist returns 404, the same as an invoice of another merchant.
    *
    * Paygentic selects the payment provider from your connected payment account. The response reports the provider.
    *
@@ -239,7 +239,7 @@ export class InvoicesV2 extends ClientSDK {
    *
    * A 500 response has the standard error body, not `retry_payment_result`. It is an internal error, and a retry does not fix it.
    *
-   * An invoice that does not exist returns 403, the same as an invoice of another merchant.
+   * An invoice that does not exist returns 404, the same as an invoice of another merchant.
    *
    * This operation is rate limited to one call each minute for each invoice.
    */

package/src/sdk/webhooks.ts

@@ -85,7 +85,7 @@ export class Webhooks extends ClientSDK {
    * Get Portal Access
    *
    * @remarks
-   * Returns a link to the webhook portal, where you add endpoints, choose event types, read the signing secret and inspect deliveries. The link opens without a login and expires one hour after it is issued, at `expiresAt`. Treat it as a secret. Returns 404 unless webhooks are enabled.
+   * Returns a link to the webhook portal, where you add endpoints, choose event types, read the signing secret and inspect deliveries. The link opens without a login and expires one hour after it is issued, at `expiresAt`. Treat it as a secret. The link is read-only unless the caller holds `webhooks:write`: a read-only portal shows endpoints and deliveries but does not let you add or change endpoints, read the signing secret or replay messages. Returns 404 unless webhooks are enabled.
    */
   async getPortal(
     request?: operations.GetWebhookPortalRequest | undefined,