@schematichq/schematic-typescript-node 1.1.9 → 1.1.10

package/Client.d.ts

@@ -19,6 +19,8 @@ import { Webhooks } from "./api/resources/webhooks/client/Client";
 export declare namespace SchematicClient {
     interface Options {
         environment?: core.Supplier<environments.SchematicEnvironment | string>;
+        /** Specify a custom URL to connect the client to. */
+        baseUrl?: core.Supplier<string>;
         apiKey: core.Supplier<string>;
         fetcher?: core.FetchFunction;
     }
@@ -29,35 +31,37 @@ export declare namespace SchematicClient {
         maxRetries?: number;
         /** A hook to abort the request. */
         abortSignal?: AbortSignal;
+        /** Additional headers to include in the request. */
+        headers?: Record<string, string>;
     }
 }
 export declare class SchematicClient {
     protected readonly _options: SchematicClient.Options;
-    constructor(_options: SchematicClient.Options);
     protected _accounts: Accounts | undefined;
-    get accounts(): Accounts;
     protected _features: Features | undefined;
-    get features(): Features;
     protected _billing: Billing | undefined;
-    get billing(): Billing;
     protected _checkout: Checkout | undefined;
-    get checkout(): Checkout;
     protected _companies: Companies | undefined;
-    get companies(): Companies;
     protected _entitlements: Entitlements | undefined;
-    get entitlements(): Entitlements;
     protected _plans: Plans | undefined;
-    get plans(): Plans;
     protected _components: Components | undefined;
-    get components(): Components;
     protected _crm: Crm | undefined;
-    get crm(): Crm;
     protected _events: Events | undefined;
-    get events(): Events;
     protected _plangroups: Plangroups | undefined;
-    get plangroups(): Plangroups;
     protected _accesstokens: Accesstokens | undefined;
-    get accesstokens(): Accesstokens;
     protected _webhooks: Webhooks | undefined;
+    constructor(_options: SchematicClient.Options);
+    get accounts(): Accounts;
+    get features(): Features;
+    get billing(): Billing;
+    get checkout(): Checkout;
+    get companies(): Companies;
+    get entitlements(): Entitlements;
+    get plans(): Plans;
+    get components(): Components;
+    get crm(): Crm;
+    get events(): Events;
+    get plangroups(): Plangroups;
+    get accesstokens(): Accesstokens;
     get webhooks(): Webhooks;
 }

package/README.md

@@ -144,6 +144,22 @@ client.close();
 
 This call is non-blocking and there is no response to check.
 
+If you want to record large numbers of the same event at once, or perhaps measure usage in terms of a unit like tokens or memory, you can optionally specify a quantity for your event:
+
+```ts
+client.track({
+    event: "some-action",
+    company: {
+        id: "your-company-id",
+    },
+    user: {
+        email: "wcoyote@acme.net",
+        userId: "your-user-id",
+    },
+    quantity: 10,
+});
+```
+
 ### 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:
@@ -254,6 +270,187 @@ client.close();
 
 The Schematic API supports many operations beyond these, accessible via the API modules on the client, `Accounts`, `Billing`, `Companies`, `Entitlements`, `Events`, `Features`, and `Plans`.
 
+## Webhook Verification
+
+Schematic can send webhooks to notify your application of events. To ensure the security of these webhooks, Schematic signs each request using HMAC-SHA256. The SDK provides utility functions to verify these signatures.
+
+### Verifying Webhook Signatures
+
+When your application receives a webhook request from Schematic, you should verify its signature to ensure it's authentic. The SDK provides simple functions to verify webhook signatures. Here's how to use them in different frameworks:
+
+#### Express
+
+```ts
+import express from "express";
+import {
+    verifyWebhookSignature,
+    WebhookSignatureError,
+    WEBHOOK_SIGNATURE_HEADER,
+    WEBHOOK_TIMESTAMP_HEADER,
+} from "@schematichq/schematic-typescript-node";
+
+// Note: Schematic webhooks use these headers:
+// - X-Schematic-Webhook-Signature: Contains the HMAC-SHA256 signature
+// - X-Schematic-Webhook-Timestamp: Contains the timestamp when the webhook was sent
+
+const app = express();
+
+// Use a middleware that captures raw body for signature verification
+app.use(
+    "/webhooks/schematic",
+    express.json({
+        verify: (req, res, buf) => {
+            if (buf && buf.length) {
+                (req as any).rawBody = buf;
+            }
+        },
+    })
+);
+
+app.post("/webhooks/schematic", (req, res) => {
+    try {
+        const webhookSecret = "your-webhook-secret"; // Get this from the Schematic app
+
+        // Verify the webhook signature using the captured raw body
+        verifyWebhookSignature(req, webhookSecret);
+
+        // Process the webhook payload
+        const data = req.body;
+        console.log("Webhook verified:", data);
+
+        res.status(200).end();
+    } catch (error) {
+        if (error instanceof WebhookSignatureError) {
+            console.error("Webhook verification failed:", error.message);
+            return res.status(400).json({ error: error.message });
+        }
+
+        console.error("Error processing webhook:", error);
+        res.status(500).json({ error: "Internal server error" });
+    }
+});
+
+const PORT = 3000;
+app.listen(PORT, () => {
+    console.log(`Server running on port ${PORT}`);
+});
+```
+
+#### Node HTTP Server
+
+```ts
+import http from "http";
+import {
+    verifySignature,
+    WebhookSignatureError,
+    WEBHOOK_SIGNATURE_HEADER,
+    WEBHOOK_TIMESTAMP_HEADER,
+} from "@schematichq/schematic-typescript-node";
+
+const webhookSecret = "your-webhook-secret"; // Get this from the Schematic app
+
+const server = http.createServer(async (req, res) => {
+    if (req.url === "/webhooks/schematic" && req.method === "POST") {
+        // Collect the request body
+        let body = "";
+        for await (const chunk of req) {
+            body += chunk.toString();
+        }
+
+        try {
+            // Get the headers
+            const signature = req.headers[WEBHOOK_SIGNATURE_HEADER.toLowerCase()] as string;
+            const timestamp = req.headers[WEBHOOK_TIMESTAMP_HEADER.toLowerCase()] as string;
+
+            // Verify the signature
+            verifySignature(body, signature, timestamp, webhookSecret);
+
+            // Process the webhook payload
+            const data = JSON.parse(body);
+            console.log("Webhook verified:", data);
+
+            res.statusCode = 200;
+            res.end();
+        } catch (error) {
+            if (error instanceof WebhookSignatureError) {
+                console.error("Webhook verification failed:", error.message);
+                res.statusCode = 400;
+                res.end(JSON.stringify({ error: error.message }));
+                return;
+            }
+
+            console.error("Error processing webhook:", error);
+            res.statusCode = 500;
+            res.end(JSON.stringify({ error: "Internal server error" }));
+        }
+    } else {
+        res.statusCode = 404;
+        res.end();
+    }
+});
+
+const PORT = 3000;
+server.listen(PORT, () => {
+    console.log(`Server running on port ${PORT}`);
+});
+```
+
+#### Next.js API Routes
+
+```ts
+// pages/api/webhooks/schematic.ts
+import type { NextApiRequest, NextApiResponse } from "next";
+import {
+    verifyWebhookSignature,
+    WebhookSignatureError,
+    WEBHOOK_SIGNATURE_HEADER,
+    WEBHOOK_TIMESTAMP_HEADER,
+} from "@schematichq/schematic-typescript-node";
+import { buffer } from "micro";
+
+// Schematic webhooks use these headers:
+// - X-Schematic-Webhook-Signature: Contains the HMAC-SHA256 signature
+// - X-Schematic-Webhook-Timestamp: Contains the timestamp when the webhook was sent
+
+// Disable body parsing to get the raw body
+export const config = {
+    api: {
+        bodyParser: false,
+    },
+};
+
+export default async function handler(req: NextApiRequest, res: NextApiResponse) {
+    if (req.method !== "POST") {
+        return res.status(405).end("Method not allowed");
+    }
+
+    try {
+        const webhookSecret = process.env.SCHEMATIC_WEBHOOK_SECRET!;
+        const rawBody = await buffer(req);
+
+        // Verify the webhook signature
+        verifyWebhookSignature(req, webhookSecret, rawBody);
+
+        // Parse the webhook payload
+        const payload = JSON.parse(rawBody.toString());
+        console.log("Webhook verified:", payload);
+
+        // Process the webhook event
+        // ...
+
+        res.status(200).end();
+    } catch (error) {
+        if (error instanceof WebhookSignatureError) {
+            console.error("Webhook verification failed:", error.message);
+            return res.status(400).json({ error: error.message });
+        }
+
+        console.error("Error processing webhook:", error);
+        res.status(500).json({ error: "Internal server error" });
+    }
+}
+```
+
 ## Testing
 
 ### Offline mode

package/api/errors/BadRequestError.js

@@ -18,13 +18,23 @@ var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (
 }) : function(o, v) {
     o["default"] = v;
 });
-var __importStar = (this && this.__importStar) || function (mod) {
-    if (mod && mod.__esModule) return mod;
-    var result = {};
-    if (mod != null) for (var k in mod) if (k !== "default" && Object.prototype.hasOwnProperty.call(mod, k)) __createBinding(result, mod, k);
-    __setModuleDefault(result, mod);
-    return result;
-};
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.BadRequestError = void 0;
 const errors = __importStar(require("../../errors/index"));

package/api/errors/ForbiddenError.js

@@ -18,13 +18,23 @@ var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (
 }) : function(o, v) {
     o["default"] = v;
 });
-var __importStar = (this && this.__importStar) || function (mod) {
-    if (mod && mod.__esModule) return mod;
-    var result = {};
-    if (mod != null) for (var k in mod) if (k !== "default" && Object.prototype.hasOwnProperty.call(mod, k)) __createBinding(result, mod, k);
-    __setModuleDefault(result, mod);
-    return result;
-};
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.ForbiddenError = void 0;
 const errors = __importStar(require("../../errors/index"));

package/api/errors/InternalServerError.js

@@ -18,13 +18,23 @@ var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (
 }) : function(o, v) {
     o["default"] = v;
 });
-var __importStar = (this && this.__importStar) || function (mod) {
-    if (mod && mod.__esModule) return mod;
-    var result = {};
-    if (mod != null) for (var k in mod) if (k !== "default" && Object.prototype.hasOwnProperty.call(mod, k)) __createBinding(result, mod, k);
-    __setModuleDefault(result, mod);
-    return result;
-};
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.InternalServerError = void 0;
 const errors = __importStar(require("../../errors/index"));

package/api/errors/NotFoundError.js

@@ -18,13 +18,23 @@ var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (
 }) : function(o, v) {
     o["default"] = v;
 });
-var __importStar = (this && this.__importStar) || function (mod) {
-    if (mod && mod.__esModule) return mod;
-    var result = {};
-    if (mod != null) for (var k in mod) if (k !== "default" && Object.prototype.hasOwnProperty.call(mod, k)) __createBinding(result, mod, k);
-    __setModuleDefault(result, mod);
-    return result;
-};
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.NotFoundError = void 0;
 const errors = __importStar(require("../../errors/index"));

package/api/errors/UnauthorizedError.js

@@ -18,13 +18,23 @@ var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (
 }) : function(o, v) {
     o["default"] = v;
 });
-var __importStar = (this && this.__importStar) || function (mod) {
-    if (mod && mod.__esModule) return mod;
-    var result = {};
-    if (mod != null) for (var k in mod) if (k !== "default" && Object.prototype.hasOwnProperty.call(mod, k)) __createBinding(result, mod, k);
-    __setModuleDefault(result, mod);
-    return result;
-};
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.UnauthorizedError = void 0;
 const errors = __importStar(require("../../errors/index"));

package/api/resources/accesstokens/client/Client.d.ts

@@ -7,6 +7,8 @@ import * as Schematic from "../../../index";
 export declare namespace Accesstokens {
     interface Options {
         environment?: core.Supplier<environments.SchematicEnvironment | string>;
+        /** Specify a custom URL to connect the client to. */
+        baseUrl?: core.Supplier<string>;
         apiKey: core.Supplier<string>;
         fetcher?: core.FetchFunction;
     }
@@ -17,6 +19,8 @@ export declare namespace Accesstokens {
         maxRetries?: number;
         /** A hook to abort the request. */
         abortSignal?: AbortSignal;
+        /** Additional headers to include in the request. */
+        headers?: Record<string, string>;
     }
 }
 export declare class Accesstokens {

package/api/resources/accesstokens/client/Client.js

@@ -18,13 +18,23 @@ var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (
 }) : function(o, v) {
     o["default"] = v;
 });
-var __importStar = (this && this.__importStar) || function (mod) {
-    if (mod && mod.__esModule) return mod;
-    var result = {};
-    if (mod != null) for (var k in mod) if (k !== "default" && Object.prototype.hasOwnProperty.call(mod, k)) __createBinding(result, mod, k);
-    __setModuleDefault(result, mod);
-    return result;
-};
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
 var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, generator) {
     function adopt(value) { return value instanceof P ? value : new P(function (resolve) { resolve(value); }); }
     return new (P || (P = Promise))(function (resolve, reject) {
@@ -67,12 +77,12 @@ class Accesstokens {
      *     })
      */
     issueTemporaryAccessToken(request, requestOptions) {
-        var _a, _b;
         return __awaiter(this, void 0, void 0, function* () {
+            var _a, _b, _c;
             const _response = yield ((_a = this._options.fetcher) !== null && _a !== void 0 ? _a : core.fetcher)({
-                url: (0, url_join_1.default)((_b = (yield core.Supplier.get(this._options.environment))) !== null && _b !== void 0 ? _b : environments.SchematicEnvironment.Default, "temporary-access-tokens"),
+                url: (0, url_join_1.default)((_c = (_b = (yield core.Supplier.get(this._options.baseUrl))) !== null && _b !== void 0 ? _b : (yield core.Supplier.get(this._options.environment))) !== null && _c !== void 0 ? _c : environments.SchematicEnvironment.Default, "temporary-access-tokens"),
                 method: "POST",
-                headers: Object.assign({ "X-Fern-Language": "JavaScript", "X-Fern-SDK-Name": "@schematichq/schematic-typescript-node", "X-Fern-SDK-Version": "1.1.9", "User-Agent": "@schematichq/schematic-typescript-node/1.1.9", "X-Fern-Runtime": core.RUNTIME.type, "X-Fern-Runtime-Version": core.RUNTIME.version }, (yield this._getCustomAuthorizationHeaders())),
+                headers: Object.assign(Object.assign({ "X-Fern-Language": "JavaScript", "X-Fern-SDK-Name": "@schematichq/schematic-typescript-node", "X-Fern-SDK-Version": "1.1.10", "User-Agent": "@schematichq/schematic-typescript-node/1.1.10", "X-Fern-Runtime": core.RUNTIME.type, "X-Fern-Runtime-Version": core.RUNTIME.version }, (yield this._getCustomAuthorizationHeaders())), requestOptions === null || requestOptions === void 0 ? void 0 : requestOptions.headers),
                 contentType: "application/json",
                 requestType: "json",
                 body: serializers.IssueTemporaryAccessTokenRequestBody.jsonOrThrow(request, {
@@ -139,7 +149,7 @@ class Accesstokens {
                         body: _response.error.rawBody,
                     });
                 case "timeout":
-                    throw new errors.SchematicTimeoutError();
+                    throw new errors.SchematicTimeoutError("Timeout exceeded when calling POST /temporary-access-tokens.");
                 case "unknown":
                     throw new errors.SchematicError({
                         message: _response.error.errorMessage,

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

@@ -7,6 +7,8 @@ import * as Schematic from "../../../index";
 export declare namespace Accounts {
     interface Options {
         environment?: core.Supplier<environments.SchematicEnvironment | string>;
+        /** Specify a custom URL to connect the client to. */
+        baseUrl?: core.Supplier<string>;
         apiKey: core.Supplier<string>;
         fetcher?: core.FetchFunction;
     }
@@ -17,6 +19,8 @@ export declare namespace Accounts {
         maxRetries?: number;
         /** A hook to abort the request. */
         abortSignal?: AbortSignal;
+        /** Additional headers to include in the request. */
+        headers?: Record<string, string>;
     }
 }
 export declare class Accounts {