@schematichq/schematic-typescript-node 1.4.6 → 1.4.7

package/README.md

@@ -1,4 +1,4 @@
-# schematic-typescript-node
+# Schematic Typescript Node SDK
 
 ## Installation and Setup
 
@@ -153,7 +153,19 @@ const client = new SchematicClient({
 client.close();
 ```
 
-If no logger is provided, the client will use a default console logger that outputs to the standard console methods.
+If no logger is provided, the client uses a default console logger. By default it only emits `warn` and `error` messages; `debug` and `info` are suppressed to keep production output quiet. Use the `logLevel` option to raise or lower the verbosity of the default logger:
+
+```ts
+import { SchematicClient, LogLevel } from "@schematichq/schematic-typescript-node";
+
+const apiKey = process.env.SCHEMATIC_API_KEY;
+const client = new SchematicClient({
+    apiKey,
+    logLevel: "debug", // or LogLevel.Debug — emit all levels (debug, info, warn, error)
+});
+```
+
+The `logLevel` option only affects the default console logger. When you supply your own `logger`, its level configuration is respected as-is and `logLevel` is ignored.
 
 ## Usage examples
 
@@ -234,6 +246,42 @@ client.track({
 });
 ```
 
+Both `track` and `identify` accept an optional second argument for event metadata. Supply an `idempotencyKey` to deduplicate events (duplicates with the same key, scoped to the environment, are dropped server-side for 24 hours):
+
+```ts
+client.track(
+    {
+        event: "some-action",
+        company: { id: "your-company-id" },
+    },
+    { idempotencyKey: "your-unique-key" },
+);
+
+client.identify(
+    {
+        keys: { userId: "your-user-id" },
+        name: "Wile E. Coyote",
+    },
+    { idempotencyKey: "your-unique-key" },
+);
+```
+
+For `track`, you can also set a trusted client clock to use your own timestamp as the effective event time, and backfill historical data without affecting billing. Both require a secret API key:
+
+```ts
+client.track(
+    {
+        event: "some-action",
+        company: { id: "your-company-id" },
+    },
+    {
+        sentAt: new Date("2026-01-01T00:00:00Z"),
+        trustedClientClock: true,
+        backfill: true,
+    },
+);
+```
+
 ### Creating and updating companies
 
 Although it is faster to create companies and users via identify events, if you need to handle a response, you can use the companies API to upsert companies. Because you use your own identifiers to identify companies, rather than a Schematic company ID, creating and updating companies are both done via the same upsert operation:
@@ -601,6 +649,64 @@ export default async function handler(req: NextApiRequest, res: NextApiResponse)
 }
 ```
 
+## Caching
+
+### Local Caching
+
+By default, the client will do some local caching for flag checks. You can customize this behavior by specifying the max size of the cache and the max age of the cache (in milliseconds) as shown in the setup section above.
+
+### Cloudflare KV Caching
+
+If you're using Cloudflare Workers, you can leverage Cloudflare's KV storage for caching flag check results. This provides a more persistent and distributed cache compared to the local in-memory cache.
+
+To use Cloudflare KV caching, you'll need to install the Cloudflare adapter package:
+
+```bash
+npm install @schematichq/schematic-typescript-cloudflare
+# or
+yarn add @schematichq/schematic-typescript-cloudflare
+# or
+pnpm add @schematichq/schematic-typescript-cloudflare
+```
+
+Then, in your Cloudflare Worker, you can set up the client with KV caching:
+
+```typescript
+import { SchematicClient } from "@schematichq/schematic-typescript-node";
+import { CloudflareKVCache } from "@schematichq/schematic-typescript-cloudflare";
+
+// Inside a Cloudflare Worker
+export default {
+  async fetch(request, env, ctx) {
+    // Create a CloudflareKVCache instance
+    const cache = new CloudflareKVCache<boolean>(env.MY_KV_NAMESPACE, {
+      ttl: 1000 * 60 * 60, // 1 hour cache TTL
+      keyPrefix: 'schematic:', // Optional prefix for KV keys
+    });
+    
+    // Initialize Schematic with the KV cache
+    const schematic = new SchematicClient({
+      apiKey: env.SCHEMATIC_API_KEY,
+      cacheProviders: {
+        flagChecks: [cache],
+      }
+    });
+    
+    // Your application logic...
+    // ...
+    
+    // Don't forget to close the client when done
+    schematic.close();
+  }
+};
+```
+
+The CloudflareKVCache constructor accepts the following options:
+- `ttl`: Time-to-live for cache entries in milliseconds (default: 5000ms)
+- `keyPrefix`: Prefix to add to all KV keys (default: 'schematic:')
+
+With this setup, flag check results will be cached in your Cloudflare KV namespace, allowing for persistence across worker invocations and global distribution of your cache.
+
 ## DataStream
 
 DataStream enables local flag evaluation by maintaining a WebSocket connection to Schematic and caching flag rules, company, and user data locally.
@@ -720,3 +826,13 @@ const client = new SchematicClient({
 
 client.close();
 ```
+
+## Contributing
+
+While we value open-source contributions to this SDK, this library is generated programmatically.
+Additions made directly to this library would have to be moved over to our generation code,
+otherwise they would be overwritten upon the next generated release. Feel free to open a PR as
+ a proof of concept, but know that we will not be able to merge it as-is. We suggest opening
+an issue first to discuss with us!
+
+On the other hand, contributions to the README are always very welcome!

package/dist/BaseClient.d.ts

@@ -1,6 +1,7 @@
 import { HeaderAuthProvider } from "./auth/HeaderAuthProvider";
 import * as core from "./core";
 import type * as environments from "./environments";
+export type AuthOption = false | core.AuthProvider["getAuthRequest"] | core.AuthProvider | HeaderAuthProvider.AuthOptions;
 export type BaseClientOptions = {
     environment?: core.Supplier<environments.SchematicEnvironment | string>;
     /** Specify a custom URL to connect the client to. */
@@ -16,6 +17,8 @@ export type BaseClientOptions = {
     fetcher?: core.FetchFunction;
     /** Configure logging for the client. */
     logging?: core.logging.LogConfig | core.logging.Logger;
+    /** Override auth. Pass false to disable, a function returning auth headers, an AuthProvider, or auth options. */
+    auth?: AuthOption;
 } & HeaderAuthProvider.AuthOptions;
 export interface BaseRequestOptions {
     /** The maximum time to wait for a response in seconds. */

package/dist/Client.d.ts

@@ -10,6 +10,7 @@ import { DataexportsClient } from "./api/resources/dataexports/client/Client";
 import { EntitlementsClient } from "./api/resources/entitlements/client/Client";
 import { EventsClient } from "./api/resources/events/client/Client";
 import { FeaturesClient } from "./api/resources/features/client/Client";
+import { InsightsClient } from "./api/resources/insights/client/Client";
 import { IntegrationsapiClient } from "./api/resources/integrationsapi/client/Client";
 import { PlanbundleClient } from "./api/resources/planbundle/client/Client";
 import { PlangroupsClient } from "./api/resources/plangroups/client/Client";
@@ -35,11 +36,12 @@ export declare class SchematicClient {
     protected _entitlements: EntitlementsClient | undefined;
     protected _plans: PlansClient | undefined;
     protected _components: ComponentsClient | undefined;
+    protected _planbundle: PlanbundleClient | undefined;
     protected _dataexports: DataexportsClient | undefined;
     protected _events: EventsClient | undefined;
     protected _features: FeaturesClient | undefined;
+    protected _insights: InsightsClient | undefined;
     protected _integrationsapi: IntegrationsapiClient | undefined;
-    protected _planbundle: PlanbundleClient | undefined;
     protected _plangroups: PlangroupsClient | undefined;
     protected _planmigrations: PlanmigrationsClient | undefined;
     protected _componentspublic: ComponentspublicClient | undefined;
@@ -55,35 +57,18 @@ export declare class SchematicClient {
     get entitlements(): EntitlementsClient;
     get plans(): PlansClient;
     get components(): ComponentsClient;
+    get planbundle(): PlanbundleClient;
     get dataexports(): DataexportsClient;
     get events(): EventsClient;
     get features(): FeaturesClient;
+    get insights(): InsightsClient;
     get integrationsapi(): IntegrationsapiClient;
-    get planbundle(): PlanbundleClient;
     get plangroups(): PlangroupsClient;
     get planmigrations(): PlanmigrationsClient;
     get componentspublic(): ComponentspublicClient;
     get scheduledcheckout(): ScheduledcheckoutClient;
     get accesstokens(): AccesstokensClient;
     get webhooks(): WebhooksClient;
-    /**
-     * @param {string} plan_audience_id
-     * @param {SchematicClient.RequestOptions} requestOptions - Request-specific configuration.
-     *
-     * @example
-     *     await client.putPlanAudiencesPlanAudienceId("plan_audience_id")
-     */
-    putPlanAudiencesPlanAudienceId(plan_audience_id: string, requestOptions?: SchematicClient.RequestOptions): core.HttpResponsePromise<void>;
-    private __putPlanAudiencesPlanAudienceId;
-    /**
-     * @param {string} plan_audience_id
-     * @param {SchematicClient.RequestOptions} requestOptions - Request-specific configuration.
-     *
-     * @example
-     *     await client.deletePlanAudiencesPlanAudienceId("plan_audience_id")
-     */
-    deletePlanAudiencesPlanAudienceId(plan_audience_id: string, requestOptions?: SchematicClient.RequestOptions): core.HttpResponsePromise<void>;
-    private __deletePlanAudiencesPlanAudienceId;
     /**
      * Make a passthrough request using the SDK's configured auth, retry, logging, etc.
      * This is useful for making requests to endpoints not yet supported in the SDK.

package/dist/api/resources/accounts/client/Client.d.ts

@@ -22,6 +22,7 @@ export declare class AccountsClient {
      *
      * @example
      *     await client.accounts.listAccountMembers({
+     *         ids: ["ids"],
      *         q: "q",
      *         limit: 1000000,
      *         offset: 1000000
@@ -217,6 +218,7 @@ export declare class AccountsClient {
      *
      * @example
      *     await client.accounts.listEnvironments({
+     *         ids: ["ids"],
      *         limit: 1000000,
      *         offset: 1000000
      *     })

package/dist/api/resources/accounts/client/requests/ListAccountMembersRequest.d.ts

@@ -1,6 +1,7 @@
 /**
  * @example
  *     {
+ *         ids: ["ids"],
  *         q: "q",
  *         limit: 1000000,
  *         offset: 1000000

package/dist/api/resources/accounts/client/requests/ListEnvironmentsRequest.d.ts

@@ -1,6 +1,7 @@
 /**
  * @example
  *     {
+ *         ids: ["ids"],
  *         limit: 1000000,
  *         offset: 1000000
  *     }

package/dist/api/resources/billing/client/Client.d.ts

@@ -88,6 +88,7 @@ export declare class BillingClient {
      *
      * @example
      *     await client.billing.listCustomersWithSubscriptions({
+     *         companyIds: ["company_ids"],
      *         name: "name",
      *         providerType: "orb",
      *         q: "q",
@@ -109,6 +110,7 @@ export declare class BillingClient {
      *
      * @example
      *     await client.billing.countCustomers({
+     *         companyIds: ["company_ids"],
      *         name: "name",
      *         providerType: "orb",
      *         q: "q",
@@ -240,6 +242,21 @@ export declare class BillingClient {
      */
     upsertPaymentMethod(request: Schematic.CreatePaymentMethodRequestBody, requestOptions?: BillingClient.RequestOptions): core.HttpResponsePromise<Schematic.UpsertPaymentMethodResponse>;
     private __upsertPaymentMethod;
+    /**
+     * @param {string} billing_id - billing_id
+     * @param {BillingClient.RequestOptions} requestOptions - Request-specific configuration.
+     *
+     * @throws {@link Schematic.BadRequestError}
+     * @throws {@link Schematic.UnauthorizedError}
+     * @throws {@link Schematic.ForbiddenError}
+     * @throws {@link Schematic.NotFoundError}
+     * @throws {@link Schematic.InternalServerError}
+     *
+     * @example
+     *     await client.billing.deletePaymentMethodByExternalId("billing_id")
+     */
+    deletePaymentMethodByExternalId(billing_id: string, requestOptions?: BillingClient.RequestOptions): core.HttpResponsePromise<Schematic.DeletePaymentMethodByExternalIdResponse>;
+    private __deletePaymentMethodByExternalId;
     /**
      * @param {Schematic.ListBillingPricesRequest} request
      * @param {BillingClient.RequestOptions} requestOptions - Request-specific configuration.
@@ -255,10 +272,12 @@ export declare class BillingClient {
      *         currency: "currency",
      *         forInitialPlan: true,
      *         forTrialExpiryPlan: true,
+     *         ids: ["ids"],
      *         interval: "interval",
      *         isActive: true,
      *         price: 1000000,
      *         productId: "product_id",
+     *         productIds: ["product_ids"],
      *         providerType: "orb",
      *         q: "q",
      *         tiersMode: "graduated",
@@ -328,10 +347,12 @@ export declare class BillingClient {
      *         currency: "currency",
      *         forInitialPlan: true,
      *         forTrialExpiryPlan: true,
+     *         ids: ["ids"],
      *         interval: "interval",
      *         isActive: true,
      *         price: 1000000,
      *         productId: "product_id",
+     *         productIds: ["product_ids"],
      *         providerType: "orb",
      *         q: "q",
      *         tiersMode: "graduated",
@@ -388,11 +409,13 @@ export declare class BillingClient {
      *
      * @example
      *     await client.billing.listBillingProducts({
+     *         ids: ["ids"],
      *         isActive: true,
      *         name: "name",
      *         priceUsageType: "licensed",
      *         providerType: "orb",
      *         q: "q",
+     *         recurringChargesOnly: true,
      *         withOneTimeCharges: true,
      *         withPricesOnly: true,
      *         withZeroPrice: true,
@@ -415,11 +438,13 @@ export declare class BillingClient {
      *
      * @example
      *     await client.billing.countBillingProducts({
+     *         ids: ["ids"],
      *         isActive: true,
      *         name: "name",
      *         priceUsageType: "licensed",
      *         providerType: "orb",
      *         q: "q",
+     *         recurringChargesOnly: true,
      *         withOneTimeCharges: true,
      *         withPricesOnly: true,
      *         withZeroPrice: true,

package/dist/api/resources/billing/client/requests/CountBillingProductsRequest.d.ts

@@ -2,11 +2,13 @@ import type * as Schematic from "../../../../index";
 /**
  * @example
  *     {
+ *         ids: ["ids"],
  *         isActive: true,
  *         name: "name",
  *         priceUsageType: "licensed",
  *         providerType: "orb",
  *         q: "q",
+ *         recurringChargesOnly: true,
  *         withOneTimeCharges: true,
  *         withPricesOnly: true,
  *         withZeroPrice: true,
@@ -23,6 +25,8 @@ export interface CountBillingProductsRequest {
     priceUsageType?: Schematic.BillingPriceUsageType;
     providerType?: Schematic.BillingProviderType;
     q?: string;
+    /** Filter to products that have at least one recurring price */
+    recurringChargesOnly?: boolean;
     /** Filter products that are one time charges */
     withOneTimeCharges?: boolean;
     /** Filter products that have prices */

package/dist/api/resources/billing/client/requests/CountCustomersRequest.d.ts

@@ -2,6 +2,7 @@ import type * as Schematic from "../../../../index";
 /**
  * @example
  *     {
+ *         companyIds: ["company_ids"],
  *         name: "name",
  *         providerType: "orb",
  *         q: "q",

package/dist/api/resources/billing/client/requests/CreateBillingPriceRequestBody.d.ts

@@ -21,8 +21,10 @@ export interface CreateBillingPriceRequestBody {
     currency: string;
     externalAccountId: string;
     interval: string;
+    intervalCount?: number;
     isActive: boolean;
     meterId?: string;
+    nickname?: string;
     packageSize?: number;
     price: number;
     priceDecimal?: string;

package/dist/api/resources/billing/client/requests/ListBillingPricesRequest.d.ts

@@ -5,10 +5,12 @@ import type * as Schematic from "../../../../index";
  *         currency: "currency",
  *         forInitialPlan: true,
  *         forTrialExpiryPlan: true,
+ *         ids: ["ids"],
  *         interval: "interval",
  *         isActive: true,
  *         price: 1000000,
  *         productId: "product_id",
+ *         productIds: ["product_ids"],
  *         providerType: "orb",
  *         q: "q",
  *         tiersMode: "graduated",

package/dist/api/resources/billing/client/requests/ListBillingProductPricesRequest.d.ts

@@ -5,10 +5,12 @@ import type * as Schematic from "../../../../index";
  *         currency: "currency",
  *         forInitialPlan: true,
  *         forTrialExpiryPlan: true,
+ *         ids: ["ids"],
  *         interval: "interval",
  *         isActive: true,
  *         price: 1000000,
  *         productId: "product_id",
+ *         productIds: ["product_ids"],
  *         providerType: "orb",
  *         q: "q",
  *         tiersMode: "graduated",

package/dist/api/resources/billing/client/requests/ListBillingProductsRequest.d.ts

@@ -2,11 +2,13 @@ import type * as Schematic from "../../../../index";
 /**
  * @example
  *     {
+ *         ids: ["ids"],
  *         isActive: true,
  *         name: "name",
  *         priceUsageType: "licensed",
  *         providerType: "orb",
  *         q: "q",
+ *         recurringChargesOnly: true,
  *         withOneTimeCharges: true,
  *         withPricesOnly: true,
  *         withZeroPrice: true,
@@ -23,6 +25,8 @@ export interface ListBillingProductsRequest {
     priceUsageType?: Schematic.BillingPriceUsageType;
     providerType?: Schematic.BillingProviderType;
     q?: string;
+    /** Filter to products that have at least one recurring price */
+    recurringChargesOnly?: boolean;
     /** Filter products that are one time charges */
     withOneTimeCharges?: boolean;
     /** Filter products that have prices */

package/dist/api/resources/billing/client/requests/ListCustomersWithSubscriptionsRequest.d.ts

@@ -2,6 +2,7 @@ import type * as Schematic from "../../../../index";
 /**
  * @example
  *     {
+ *         companyIds: ["company_ids"],
  *         name: "name",
  *         providerType: "orb",
  *         q: "q",

package/dist/api/resources/billing/types/CountBillingProductsParams.d.ts

@@ -14,6 +14,8 @@ export interface CountBillingProductsParams {
     priceUsageType?: Schematic.BillingPriceUsageType;
     providerType?: Schematic.BillingProviderType;
     q?: string;
+    /** Filter to products that have at least one recurring price */
+    recurringChargesOnly?: boolean;
     /** Filter products that are one time charges */
     withOneTimeCharges?: boolean;
     /** Filter products that have prices */

package/dist/api/resources/billing/types/DeletePaymentMethodByExternalIdResponse.d.ts

@@ -0,0 +1,6 @@
+import type * as Schematic from "../../../index";
+export interface DeletePaymentMethodByExternalIdResponse {
+    data: Schematic.DeleteResponse;
+    /** Input parameters */
+    params: Record<string, unknown>;
+}

package/dist/api/resources/billing/types/ListBillingProductsParams.d.ts

@@ -14,6 +14,8 @@ export interface ListBillingProductsParams {
     priceUsageType?: Schematic.BillingPriceUsageType;
     providerType?: Schematic.BillingProviderType;
     q?: string;
+    /** Filter to products that have at least one recurring price */
+    recurringChargesOnly?: boolean;
     /** Filter products that are one time charges */
     withOneTimeCharges?: boolean;
     /** Filter products that have prices */

package/dist/api/resources/billing/types/index.d.ts

@@ -3,6 +3,7 @@ export * from "./CountBillingProductsResponse";
 export * from "./CountCustomersParams";
 export * from "./CountCustomersResponse";
 export * from "./DeleteBillingProductResponse";
+export * from "./DeletePaymentMethodByExternalIdResponse";
 export * from "./DeleteProductPriceResponse";
 export * from "./ListBillingPricesParams";
 export * from "./ListBillingPricesResponse";

package/dist/api/resources/checkout/client/Client.d.ts

@@ -26,6 +26,9 @@ export declare class CheckoutClient {
      *                 addOnId: "add_on_id",
      *                 priceId: "price_id"
      *             }],
+     *         autoTopupOverrides: [{
+     *                 planCreditGrantId: "plan_credit_grant_id"
+     *             }],
      *         companyId: "company_id",
      *         creditBundles: [{
      *                 bundleId: "bundle_id",
@@ -75,6 +78,9 @@ export declare class CheckoutClient {
      *                 addOnId: "add_on_id",
      *                 priceId: "price_id"
      *             }],
+     *         autoTopupOverrides: [{
+     *                 planCreditGrantId: "plan_credit_grant_id"
+     *             }],
      *         companyId: "company_id",
      *         creditBundles: [{
      *                 bundleId: "bundle_id",