Adding support for the new Usage Billing APIs (#2184)

README.md

@@ -517,6 +517,40 @@ const stripe = new Stripe('sk_test_...', {
 });
 ```
 
+### Custom requests
+
+If you would like to send a request to an undocumented API (for example you are in a private beta), or if you prefer to bypass the method definitions in the library and specify your request details directly, you can use the `rawRequest` method on the StripeClient object.
+
+```javascript
+const client = new Stripe('sk_test_...');
+
+client.rawRequest(
+    'POST',
+    '/v1/beta_endpoint',
+    { param: 123 },
+    { apiVersion: '2022-11-15; feature_beta=v3' }
+  )
+  .then((response) => /* handle response */ )
+  .catch((error) => console.error(error));
+```
+
+Or using ES modules and `async`/`await`:
+
+```javascript
+import Stripe from 'stripe';
+const stripe = new Stripe('sk_test_...');
+
+const response = await stripe.rawRequest(
+  'POST',
+  '/v1/beta_endpoint',
+  { param: 123 },
+  { apiVersion: '2022-11-15; feature_beta=v3' }
+);
+
+// handle response
+```
+
+
 ## Support
 
 New features and bug fixes are released on the latest major version of the `stripe` package. If you are on an older major version, we recommend that you upgrade to the latest in order to use the new features and bug fixes including those for security vulnerabilities. Older major versions of the package will continue to be available for use, but will not be receiving any updates.

examples/snippets/README.md

@@ -0,0 +1,27 @@
+## Setup
+
+1. From the stripe-node root folder, run `yarn build` to build the modules.
+2. Then, from this snippets folder, run `yarn` to install node dependencies for the example snippets. This will reference the local Stripe SDK modules created in step 1.
+
+If on step 2 you see an error `Error: unsure how to copy this: /Users/jar/stripe/sdks/node/.git/fsmonitor--daemon.ipc`:
+run `rm /path/to/node/sdk/.git/fsmonitor--daemon.ipc && yarn`
+This file is used by a file monitor built into git. Removing it temporarily does not seem to affect its operation, and this one liner will let `yarn` succeed.
+
+Note that if you modify the stripe-node code, you must delete your snippets `node_modules` folder and rerun these steps.
+
+## Running an example
+
+If your example is in typescript, run:
+`yarn run ts-node your_example.ts`
+
+If your example is in javascript, run:
+`node your_example.js`
+or
+`node your_example.mjs`
+
+## Adding a new example
+
+1. Clone new_example.ts
+2. Implement your example
+3. Run it (as per above)
+4. 👍

examples/snippets/meter_event_stream.ts

@@ -0,0 +1,39 @@
+import {Stripe} from 'stripe';
+
+const apiKey = '{{API_KEY}}';
+const customerId = '{{CUSTOMER_ID}}';
+
+let meterEventSession: null | any = null;
+
+async function refreshMeterEventSession() {
+  if (
+    meterEventSession === null ||
+    new Date(meterEventSession.expires_at * 1000) <= new Date()
+  ) {
+    // Create a new meter event session in case the existing session expired
+    const client = new Stripe(apiKey);
+    meterEventSession = await client.v2.billing.meterEventSession.create();
+  }
+}
+
+async function sendMeterEvent(meterEvent: any) {
+  // Refresh the meter event session, if necessary
+  await refreshMeterEventSession();
+
+  // Create a meter event
+  const client = new Stripe(meterEventSession.authentication_token);
+  await client.v2.billing.meterEventStream.create({
+    events: [meterEvent],
+  });
+}
+
+// Send meter events
+sendMeterEvent({
+  event_name: 'alpaca_ai_tokens',
+  payload: {
+    stripe_customer_id: customerId, // Replace with actual customer ID
+    value: '27',
+  },
+}).catch((error) => {
+  console.error('Error sending meter event:', error);
+});

examples/snippets/new_example.ts

@@ -0,0 +1,7 @@
+import {Stripe} from 'stripe';
+
+const apiKey = '{{API_KEY}}';
+
+console.log('Hello World');
+// const client = new Stripe(apiKey);
+// client.v2....

examples/snippets/package.json

@@ -0,0 +1,13 @@
+{
+  "name": "snippets",
+  "version": "1.0.0",
+  "description": "example Stripe SDK code snippets",
+  "main": "index.js",
+  "license": "ISC",
+  "dependencies": {
+    "express": "^4.21.0",
+    "stripe": "file:../../",
+    "ts-node": "^10.9.2",
+    "typescript": "^5.6.2"
+  }
+}

examples/snippets/stripe_webhook_handler.js

@@ -0,0 +1,36 @@
+const express = require('express');
+const {Stripe} = require('stripe');
+
+const app = express();
+
+const apiKey = process.env.STRIPE_API_KEY;
+const webhookSecret = process.env.WEBHOOK_SECRET;
+
+const client = new Stripe(apiKey);
+
+app.post(
+  '/webhook',
+  express.raw({type: 'application/json'}),
+  async (req, res) => {
+    const sig = req.headers['stripe-signature'];
+
+    try {
+      const thinEvent = client.parseThinEvent(req.body, sig, webhookSecret);
+
+      // Fetch the event data to understand the failure
+      const event = await client.v2.core.events.retrieve(thinEvent.id);
+      if (event.type == 'v1.billing.meter.error_report_triggered') {
+        const meter = await event.fetchRelatedObject();
+        const meterId = meter.id;
+        // Record the failures and alert your team
+        // Add your logic here
+      }
+      res.sendStatus(200);
+    } catch (err) {
+      console.log(`Webhook Error: ${err.stack}`);
+      res.status(400).send(`Webhook Error: ${err.message}`);
+    }
+  }
+);
+
+app.listen(4242, () => console.log('Running on port 4242'));