stripe-search-ql

The Stripe Search API is a powerful tool for flexibly searching resources like customers, charges, and subscriptions. However, hand-writing query syntax comes with several challenges:

• Syntax errors in query strings are hard to detect
• Metadata keys require proper escaping
• Stripe-specific constraints like the AND/OR mixing prohibition must be remembered
• String concatenation code becomes increasingly unreadable as queries grow more complex

stripe-search-ql solves these challenges as a TypeScript query builder. Using a fluent, chainable API, you can construct Stripe Search API queries with type safety and intuitive syntax.

Installation

npm install stripe-search-ql

Basic Usage

Field Search

import { stripeQuery } from "stripe-search-ql";
// Exact match
const query = stripeQuery()
.field("email")
.equals("amy@rocketrides.io")
.build();
// => 'email:"amy@rocketrides.io"'
// Substring match
const substringQuery = stripeQuery()
.field("email")
.contains("amy")
.build();
// => 'email~"amy"'
// Numeric comparison
const amountQuery = stripeQuery()
.field("amount")
.greaterThan(1000)
.build();
// => 'amount>1000'

Combining Multiple Conditions

// Combine conditions with AND
const andQuery = stripeQuery()
  .field("email")
  .equals("amy@rocketrides.io")
  .and()
  .field("currency")
  .equals("usd")
  .build();
// => 'email:"amy@rocketrides.io" AND currency:"usd"'
// OR operator
const orQuery = stripeQuery()
.field("currency")
.equals("usd")
.or()
.field("currency")
.equals("eur")
.build();
// => 'currency:"usd" OR currency:"eur"'

Metadata Search

// Exact match for metadata
const metadataQuery = stripeQuery()
  .metadata("donation-id")
  .equals("asdf-jkl")
  .build();
// => 'metadata["donation-id"]:"asdf-jkl"'

Negation & NULL Checks

// Negate a field
stripeQuery().not("currency").equals("jpy").build();
// => '-currency:"jpy"'
// NULL value check
stripeQuery().field("url").isNull().build();
// => 'url:null'

Customer Query Builder

A dedicated builder for customer searches is also provided. Pre-defined fields like email(), name(), and phone() make query construction even more intuitive.

import { customerQuery } from "stripe-search-ql";
const query = customerQuery()
.email()
.equals("test@example.com")
.and()
.name()
.contains("John")
.build();
// => 'email:"test@example.com" AND name~"John"'

Charge Templates

Common charge search patterns are provided as ready-to-use templates. No need to build queries from scratch.

import { chargeTemplates } from "stripe-search-ql";
// Failed charges in the last 7 days
chargeTemplates.failedInLastDays(7).build();
// High-value charges
chargeTemplates.highValue(100000).build();
// Amount range
chargeTemplates.amountBetween(1000, 5000).build();
// Filter by currency
chargeTemplates.byCurrency("usd").build();
// Extend templates with additional conditions
chargeTemplates
.failedInLastDays(7)
.and()
.field("amount")
.greaterThan(5000)
.build();

Integration with Stripe SDK

Constructed queries can be passed directly to the Stripe SDK.

import { stripeQuery } from "stripe-search-ql";
import Stripe from "stripe";
const stripe = new Stripe(process.env.STRIPE_SECRET_KEY!);
const query = stripeQuery()
.field("email")
.equals("customer@example.com")
.build();
const customers = await stripe.customers.search({
query: query,
});

Key Features

• Type-safe: TypeScript's type system catches query structure errors at compile time
• Fluent API: Intuitive and readable query construction with method chaining
• Auto-escaping: Automatically escapes special characters in string values and metadata keys
• Constraint validation: Detects Stripe Search API constraints like AND/OR mixing at runtime
• Dedicated builders: CustomerQueryBuilder specialized for customer searches
• Templates: Built-in templates for common charge search patterns
• Zero dependencies: No external library dependencies
• ES Module support: Supports modern JavaScript module systems

Limitations

• Substring match (~) requires a minimum of 3 characters
• AND and OR cannot be mixed in the same query (Stripe Search API constraint)
• Parentheses for operator precedence are not supported (Stripe Search API constraint)