stripe-search-ql

Stripe Search APIは、顧客・決済・サブスクリプションなどのリソースを柔軟に検索できる強力なAPIです。しかし、クエリ構文を手書きで構築する場合、以下のような課題があります。

• クエリ文字列のシンタックスエラーに気づきにくい
• メタデータキーのエスケープ処理を正しく行う必要がある
• AND/ORの混在禁止ルールなど、Stripe固有の制約を覚えておく必要がある
• 複雑なクエリになるほど文字列結合のコードが読みにくくなる

stripe-search-qlはこれらの課題を解決するTypeScriptクエリビルダーです。フルエントAPIによるメソッドチェーンで、型安全かつ直感的にStripe Search APIのクエリを構築できます。

インストール

npm install stripe-search-ql

基本的な使い方

フィールド検索

import { stripeQuery } from "stripe-search-ql";
// 完全一致検索
const query = stripeQuery()
.field("email")
.equals("amy@rocketrides.io")
.build();
// => 'email:"amy@rocketrides.io"'
// 部分文字列マッチ
const substringQuery = stripeQuery()
.field("email")
.contains("amy")
.build();
// => 'email~"amy"'
// 数値比較
const amountQuery = stripeQuery()
.field("amount")
.greaterThan(1000)
.build();
// => 'amount>1000'

複数条件の結合

// AND演算子で条件を組み合わせる
const andQuery = stripeQuery()
  .field("email")
  .equals("amy@rocketrides.io")
  .and()
  .field("currency")
  .equals("usd")
  .build();
// => 'email:"amy@rocketrides.io" AND currency:"usd"'
// OR演算子
const orQuery = stripeQuery()
.field("currency")
.equals("usd")
.or()
.field("currency")
.equals("eur")
.build();
// => 'currency:"usd" OR currency:"eur"'

メタデータ検索

// メタデータの完全一致
const metadataQuery = stripeQuery()
  .metadata("donation-id")
  .equals("asdf-jkl")
  .build();
// => 'metadata["donation-id"]:"asdf-jkl"'

否定・NULL値チェック

// フィールドの否定
stripeQuery().not("currency").equals("jpy").build();
// => '-currency:"jpy"'
// NULL値チェック
stripeQuery().field("url").isNull().build();
// => 'url:null'

Customer Query Builder

顧客検索に特化した専用ビルダーも提供しています。email()、name()、phone()などの事前定義フィールドにより、さらに直感的にクエリを構築できます。

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

よくある決済検索パターンをテンプレートとして提供しています。ゼロからクエリを組み立てる必要はありません。

import { chargeTemplates } from "stripe-search-ql";
// 過去7日間の失敗した決済
chargeTemplates.failedInLastDays(7).build();
// 高額決済の検索
chargeTemplates.highValue(100000).build();
// 金額範囲の指定
chargeTemplates.amountBetween(1000, 5000).build();
// 通貨での絞り込み
chargeTemplates.byCurrency("usd").build();
// テンプレートに条件を追加
chargeTemplates
.failedInLastDays(7)
.and()
.field("amount")
.greaterThan(5000)
.build();

Stripe SDKとの連携

構築したクエリは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,
});

主な特徴

• 型安全：TypeScriptの型システムにより、コンパイル時にクエリ構造のエラーを検出
• フルエントAPI：メソッドチェーンによる直感的で読みやすいクエリ構築
• 自動エスケープ：文字列値やメタデータキーの特殊文字を自動的にエスケープ
• 制約バリデーション：AND/ORの混在禁止など、Stripe Search APIの制約をランタイムで検出
• 専用ビルダー：顧客検索に特化したCustomerQueryBuilderを提供
• テンプレート：よくある決済検索パターンのテンプレートを内蔵
• ゼロ依存：外部ライブラリへの依存なし
• ESモジュール対応：最新のJavaScriptモジュールシステムをサポート

制限事項

• 部分文字列マッチ（~）は最小3文字が必要です
• 同じクエリ内でANDとORを混在させることはできません（Stripe Search APIの制約）
• 括弧による優先順位の指定はサポートされていません（Stripe Search APIの制約）