@hasna/connectors 0.0.1

package/connectors/connect-stripe/src/api/client.ts

@@ -0,0 +1,190 @@
+import type { ConnectorConfig, OutputFormat } from '../types';
+import { ConnectorApiError } from '../types';
+
+// Stripe API base URL
+const DEFAULT_BASE_URL = 'https://api.stripe.com/v1';
+const DEFAULT_API_VERSION = '2025-01-27.acacia';
+
+export interface RequestOptions {
+  method?: 'GET' | 'POST' | 'PUT' | 'DELETE' | 'PATCH';
+  params?: Record<string, string | number | boolean | undefined>;
+  body?: Record<string, unknown> | unknown[] | string;
+  headers?: Record<string, string>;
+  format?: OutputFormat;
+}
+
+/**
+ * Encode a value for form-urlencoded format with nested object support
+ * Stripe uses bracket notation: metadata[key]=value, items[0][price]=xxx
+ */
+function encodeFormData(data: Record<string, unknown>, prefix = ''): string {
+  const parts: string[] = [];
+
+  for (const [key, value] of Object.entries(data)) {
+    if (value === undefined || value === null) continue;
+
+    const encodedKey = prefix ? `${prefix}[${key}]` : key;
+
+    if (Array.isArray(value)) {
+      // Handle arrays: items[0][price]=xxx, items[1][price]=yyy
+      value.forEach((item, index) => {
+        if (typeof item === 'object' && item !== null) {
+          parts.push(encodeFormData(item as Record<string, unknown>, `${encodedKey}[${index}]`));
+        } else {
+          parts.push(`${encodeURIComponent(`${encodedKey}[${index}]`)}=${encodeURIComponent(String(item))}`);
+        }
+      });
+    } else if (typeof value === 'object') {
+      // Handle nested objects: metadata[order_id]=123
+      parts.push(encodeFormData(value as Record<string, unknown>, encodedKey));
+    } else {
+      // Handle primitives
+      parts.push(`${encodeURIComponent(encodedKey)}=${encodeURIComponent(String(value))}`);
+    }
+  }
+
+  return parts.filter(Boolean).join('&');
+}
+
+export class ConnectorClient {
+  private readonly apiKey: string;
+  private readonly apiSecret?: string;
+  private readonly baseUrl: string;
+  private readonly accountId?: string;
+  private readonly apiVersion: string;
+
+  constructor(config: ConnectorConfig) {
+    if (!config.apiKey) {
+      throw new Error('API key is required');
+    }
+    this.apiKey = config.apiKey;
+    this.apiSecret = config.apiSecret;
+    this.baseUrl = config.baseUrl || DEFAULT_BASE_URL;
+    this.accountId = config.accountId;
+    this.apiVersion = config.apiVersion || DEFAULT_API_VERSION;
+
+    // Org API keys (sk_org_*) require account ID
+    if (this.apiKey.startsWith('sk_org_') && !this.accountId) {
+      throw new Error('Account ID is required for organization API keys. Use "config set-account <accountId>" to set it.');
+    }
+  }
+
+  private buildUrl(path: string, params?: Record<string, string | number | boolean | undefined>): string {
+    const url = new URL(`${this.baseUrl}${path}`);
+
+    if (params) {
+      Object.entries(params).forEach(([key, value]) => {
+        if (value !== undefined && value !== null && value !== '') {
+          url.searchParams.append(key, String(value));
+        }
+      });
+    }
+
+    return url.toString();
+  }
+
+  /**
+   * Make an authenticated request to the Stripe API
+   * Stripe uses Bearer token authentication
+   */
+  async request<T>(path: string, options: RequestOptions = {}): Promise<T> {
+    const { method = 'GET', params, body, headers = {} } = options;
+
+    const url = this.buildUrl(path, params);
+
+    // Stripe uses Bearer token authentication
+    const requestHeaders: Record<string, string> = {
+      'Authorization': `Bearer ${this.apiKey}`,
+      'Accept': 'application/json',
+      'Stripe-Version': this.apiVersion,
+      ...headers,
+    };
+
+    // Add Stripe-Context for organization API keys
+    if (this.accountId) {
+      requestHeaders['Stripe-Context'] = this.accountId;
+    }
+
+    // Stripe uses form-urlencoded for POST/PUT/PATCH requests
+    if (body && ['POST', 'PUT', 'PATCH'].includes(method)) {
+      requestHeaders['Content-Type'] = 'application/x-www-form-urlencoded';
+    }
+
+    const fetchOptions: RequestInit = {
+      method,
+      headers: requestHeaders,
+    };
+
+    if (body && ['POST', 'PUT', 'PATCH'].includes(method)) {
+      if (typeof body === 'string') {
+        fetchOptions.body = body;
+      } else if (typeof body === 'object') {
+        fetchOptions.body = encodeFormData(body as Record<string, unknown>);
+      }
+    }
+
+    const response = await fetch(url, fetchOptions);
+
+    // Handle 204 No Content
+    if (response.status === 204) {
+      return {} as T;
+    }
+
+    // Parse response
+    let data: unknown;
+    const contentType = response.headers.get('content-type') || '';
+
+    if (contentType.includes('application/json')) {
+      const text = await response.text();
+      if (text) {
+        try {
+          data = JSON.parse(text);
+        } catch {
+          data = text;
+        }
+      }
+    } else {
+      data = await response.text();
+    }
+
+    // Handle errors
+    if (!response.ok) {
+      const errorMessage = typeof data === 'object' && data !== null
+        ? JSON.stringify(data)
+        : String(data || response.statusText);
+      throw new ConnectorApiError(errorMessage, response.status);
+    }
+
+    return data as T;
+  }
+
+  async get<T>(path: string, params?: Record<string, string | number | boolean | undefined>): Promise<T> {
+    return this.request<T>(path, { method: 'GET', params });
+  }
+
+  async post<T>(path: string, body?: Record<string, unknown> | unknown[] | string | object, params?: Record<string, string | number | boolean | undefined>): Promise<T> {
+    return this.request<T>(path, { method: 'POST', body: body as Record<string, unknown>, params });
+  }
+
+  async put<T>(path: string, body?: Record<string, unknown> | object, params?: Record<string, string | number | boolean | undefined>): Promise<T> {
+    return this.request<T>(path, { method: 'PUT', body: body as Record<string, unknown>, params });
+  }
+
+  async patch<T>(path: string, body?: Record<string, unknown> | object, params?: Record<string, string | number | boolean | undefined>): Promise<T> {
+    return this.request<T>(path, { method: 'PATCH', body: body as Record<string, unknown>, params });
+  }
+
+  async delete<T>(path: string, params?: Record<string, string | number | boolean | undefined>): Promise<T> {
+    return this.request<T>(path, { method: 'DELETE', params });
+  }
+
+  /**
+   * Get a preview of the API key (for display/debugging)
+   */
+  getApiKeyPreview(): string {
+    if (this.apiKey.length > 10) {
+      return `${this.apiKey.substring(0, 6)}...${this.apiKey.substring(this.apiKey.length - 4)}`;
+    }
+    return '***';
+  }
+}

package/connectors/connect-stripe/src/api/coupons.ts

@@ -0,0 +1,52 @@
+import type { ConnectorClient } from './client';
+import type {
+  Coupon,
+  CouponCreateParams,
+  CouponUpdateParams,
+  CouponListOptions,
+  StripeList,
+  DeletedObject,
+} from '../types';
+
+/**
+ * Stripe Coupons API
+ * https://stripe.com/docs/api/coupons
+ */
+export class CouponsApi {
+  constructor(private readonly client: ConnectorClient) {}
+
+  /**
+   * Create a coupon
+   */
+  async create(params: CouponCreateParams): Promise<Coupon> {
+    return this.client.post<Coupon>('/coupons', params);
+  }
+
+  /**
+   * Retrieve a coupon by ID
+   */
+  async get(id: string): Promise<Coupon> {
+    return this.client.get<Coupon>(`/coupons/${id}`);
+  }
+
+  /**
+   * Update a coupon
+   */
+  async update(id: string, params: CouponUpdateParams): Promise<Coupon> {
+    return this.client.post<Coupon>(`/coupons/${id}`, params);
+  }
+
+  /**
+   * List all coupons
+   */
+  async list(options?: CouponListOptions): Promise<StripeList<Coupon>> {
+    return this.client.get<StripeList<Coupon>>('/coupons', options as Record<string, string | number | boolean | undefined>);
+  }
+
+  /**
+   * Delete a coupon
+   */
+  async del(id: string): Promise<DeletedObject> {
+    return this.client.delete<DeletedObject>(`/coupons/${id}`);
+  }
+}

package/connectors/connect-stripe/src/api/customers.ts

@@ -0,0 +1,65 @@
+import type { ConnectorClient } from './client';
+import type {
+  Customer,
+  CustomerCreateParams,
+  CustomerUpdateParams,
+  CustomerListOptions,
+  StripeList,
+  StripeSearchResult,
+  DeletedObject,
+} from '../types';
+
+/**
+ * Stripe Customers API
+ * https://stripe.com/docs/api/customers
+ */
+export class CustomersApi {
+  constructor(private readonly client: ConnectorClient) {}
+
+  /**
+   * Create a customer
+   */
+  async create(params?: CustomerCreateParams): Promise<Customer> {
+    return this.client.post<Customer>('/customers', params || {});
+  }
+
+  /**
+   * Retrieve a customer by ID
+   */
+  async get(id: string): Promise<Customer> {
+    return this.client.get<Customer>(`/customers/${id}`);
+  }
+
+  /**
+   * Update a customer
+   */
+  async update(id: string, params: CustomerUpdateParams): Promise<Customer> {
+    return this.client.post<Customer>(`/customers/${id}`, params);
+  }
+
+  /**
+   * List all customers
+   */
+  async list(options?: CustomerListOptions): Promise<StripeList<Customer>> {
+    return this.client.get<StripeList<Customer>>('/customers', options as Record<string, string | number | boolean | undefined>);
+  }
+
+  /**
+   * Delete a customer
+   */
+  async del(id: string): Promise<DeletedObject> {
+    return this.client.delete<DeletedObject>(`/customers/${id}`);
+  }
+
+  /**
+   * Search customers
+   * Query syntax: https://stripe.com/docs/search#query-fields-for-customers
+   */
+  async search(query: string, options?: { limit?: number; page?: string }): Promise<StripeSearchResult<Customer>> {
+    return this.client.get<StripeSearchResult<Customer>>('/customers/search', {
+      query,
+      limit: options?.limit,
+      page: options?.page,
+    });
+  }
+}

package/connectors/connect-stripe/src/api/events.ts

@@ -0,0 +1,28 @@
+import type { ConnectorClient } from './client';
+import type {
+  Event,
+  EventListOptions,
+  StripeList,
+} from '../types';
+
+/**
+ * Stripe Events API
+ * https://stripe.com/docs/api/events
+ */
+export class EventsApi {
+  constructor(private readonly client: ConnectorClient) {}
+
+  /**
+   * Retrieve an event by ID
+   */
+  async get(id: string): Promise<Event> {
+    return this.client.get<Event>(`/events/${id}`);
+  }
+
+  /**
+   * List all events
+   */
+  async list(options?: EventListOptions): Promise<StripeList<Event>> {
+    return this.client.get<StripeList<Event>>('/events', options as Record<string, string | number | boolean | undefined>);
+  }
+}

package/connectors/connect-stripe/src/api/index.ts

@@ -0,0 +1,118 @@
+import type { ConnectorConfig } from '../types';
+import { ConnectorClient } from './client';
+import { BalanceApi } from './balance';
+import { ProductsApi } from './products';
+import { PricesApi } from './prices';
+import { CustomersApi } from './customers';
+import { SubscriptionsApi } from './subscriptions';
+import { SubscriptionItemsApi } from './subscription-items';
+import { PaymentIntentsApi } from './payment-intents';
+import { PaymentMethodsApi } from './payment-methods';
+import { ChargesApi } from './charges';
+import { InvoicesApi } from './invoices';
+import { InvoiceItemsApi } from './invoice-items';
+import { CouponsApi } from './coupons';
+import { PromotionCodesApi } from './promotion-codes';
+import { EventsApi } from './events';
+import { WebhooksApi } from './webhooks';
+import { CheckoutSessionsApi } from './checkout-sessions';
+import { PaymentLinksApi } from './payment-links';
+import { BillingPortalApi } from './billing-portal';
+
+/**
+ * Stripe API Connector class
+ */
+export class Connector {
+  private readonly client: ConnectorClient;
+
+  // API modules
+  public readonly balance: BalanceApi;
+  public readonly products: ProductsApi;
+  public readonly prices: PricesApi;
+  public readonly customers: CustomersApi;
+  public readonly subscriptions: SubscriptionsApi;
+  public readonly subscriptionItems: SubscriptionItemsApi;
+  public readonly paymentIntents: PaymentIntentsApi;
+  public readonly paymentMethods: PaymentMethodsApi;
+  public readonly charges: ChargesApi;
+  public readonly invoices: InvoicesApi;
+  public readonly invoiceItems: InvoiceItemsApi;
+  public readonly coupons: CouponsApi;
+  public readonly promotionCodes: PromotionCodesApi;
+  public readonly events: EventsApi;
+  public readonly webhooks: WebhooksApi;
+  public readonly checkoutSessions: CheckoutSessionsApi;
+  public readonly paymentLinks: PaymentLinksApi;
+  public readonly billingPortal: BillingPortalApi;
+
+  constructor(config: ConnectorConfig) {
+    this.client = new ConnectorClient(config);
+    this.balance = new BalanceApi(this.client);
+    this.products = new ProductsApi(this.client);
+    this.prices = new PricesApi(this.client);
+    this.customers = new CustomersApi(this.client);
+    this.subscriptions = new SubscriptionsApi(this.client);
+    this.subscriptionItems = new SubscriptionItemsApi(this.client);
+    this.paymentIntents = new PaymentIntentsApi(this.client);
+    this.paymentMethods = new PaymentMethodsApi(this.client);
+    this.charges = new ChargesApi(this.client);
+    this.invoices = new InvoicesApi(this.client);
+    this.invoiceItems = new InvoiceItemsApi(this.client);
+    this.coupons = new CouponsApi(this.client);
+    this.promotionCodes = new PromotionCodesApi(this.client);
+    this.events = new EventsApi(this.client);
+    this.webhooks = new WebhooksApi(this.client);
+    this.checkoutSessions = new CheckoutSessionsApi(this.client);
+    this.paymentLinks = new PaymentLinksApi(this.client);
+    this.billingPortal = new BillingPortalApi(this.client);
+  }
+
+  /**
+   * Create a client from environment variables
+   * Looks for STRIPE_API_KEY and optionally STRIPE_API_SECRET
+   */
+  static fromEnv(): Connector {
+    const apiKey = process.env.STRIPE_API_KEY;
+    const apiSecret = process.env.STRIPE_API_SECRET;
+
+    if (!apiKey) {
+      throw new Error('STRIPE_API_KEY environment variable is required');
+    }
+    return new Connector({ apiKey, apiSecret });
+  }
+
+  /**
+   * Get a preview of the API key (for debugging)
+   */
+  getApiKeyPreview(): string {
+    return this.client.getApiKeyPreview();
+  }
+
+  /**
+   * Get the underlying client for direct API access
+   */
+  getClient(): ConnectorClient {
+    return this.client;
+  }
+}
+
+// Export client and all API classes
+export { ConnectorClient } from './client';
+export { BalanceApi } from './balance';
+export { ProductsApi } from './products';
+export { PricesApi } from './prices';
+export { CustomersApi } from './customers';
+export { SubscriptionsApi } from './subscriptions';
+export { SubscriptionItemsApi } from './subscription-items';
+export { PaymentIntentsApi } from './payment-intents';
+export { PaymentMethodsApi } from './payment-methods';
+export { ChargesApi } from './charges';
+export { InvoicesApi } from './invoices';
+export { InvoiceItemsApi } from './invoice-items';
+export { CouponsApi } from './coupons';
+export { PromotionCodesApi } from './promotion-codes';
+export { EventsApi } from './events';
+export { WebhooksApi } from './webhooks';
+export { CheckoutSessionsApi } from './checkout-sessions';
+export { PaymentLinksApi } from './payment-links';
+export { BillingPortalApi } from './billing-portal';

package/connectors/connect-stripe/src/api/invoice-items.ts

@@ -0,0 +1,52 @@
+import type { ConnectorClient } from './client';
+import type {
+  InvoiceItem,
+  InvoiceItemCreateParams,
+  InvoiceItemUpdateParams,
+  InvoiceItemListOptions,
+  StripeList,
+  DeletedObject,
+} from '../types';
+
+/**
+ * Stripe Invoice Items API
+ * https://stripe.com/docs/api/invoiceitems
+ */
+export class InvoiceItemsApi {
+  constructor(private readonly client: ConnectorClient) {}
+
+  /**
+   * Create an invoice item
+   */
+  async create(params: InvoiceItemCreateParams): Promise<InvoiceItem> {
+    return this.client.post<InvoiceItem>('/invoiceitems', params);
+  }
+
+  /**
+   * Retrieve an invoice item by ID
+   */
+  async get(id: string): Promise<InvoiceItem> {
+    return this.client.get<InvoiceItem>(`/invoiceitems/${id}`);
+  }
+
+  /**
+   * Update an invoice item
+   */
+  async update(id: string, params: InvoiceItemUpdateParams): Promise<InvoiceItem> {
+    return this.client.post<InvoiceItem>(`/invoiceitems/${id}`, params);
+  }
+
+  /**
+   * List all invoice items
+   */
+  async list(options?: InvoiceItemListOptions): Promise<StripeList<InvoiceItem>> {
+    return this.client.get<StripeList<InvoiceItem>>('/invoiceitems', options as Record<string, string | number | boolean | undefined>);
+  }
+
+  /**
+   * Delete an invoice item
+   */
+  async del(id: string): Promise<DeletedObject> {
+    return this.client.delete<DeletedObject>(`/invoiceitems/${id}`);
+  }
+}

package/connectors/connect-stripe/src/api/invoices.ts

@@ -0,0 +1,102 @@
+import type { ConnectorClient } from './client';
+import type {
+  Invoice,
+  InvoiceCreateParams,
+  InvoiceUpdateParams,
+  InvoiceFinalizeParams,
+  InvoicePayParams,
+  InvoiceListOptions,
+  StripeList,
+  StripeSearchResult,
+  DeletedObject,
+} from '../types';
+
+/**
+ * Stripe Invoices API
+ * https://stripe.com/docs/api/invoices
+ */
+export class InvoicesApi {
+  constructor(private readonly client: ConnectorClient) {}
+
+  /**
+   * Create an invoice
+   */
+  async create(params?: InvoiceCreateParams): Promise<Invoice> {
+    return this.client.post<Invoice>('/invoices', params || {});
+  }
+
+  /**
+   * Retrieve an invoice by ID
+   */
+  async get(id: string): Promise<Invoice> {
+    return this.client.get<Invoice>(`/invoices/${id}`);
+  }
+
+  /**
+   * Update an invoice
+   */
+  async update(id: string, params: InvoiceUpdateParams): Promise<Invoice> {
+    return this.client.post<Invoice>(`/invoices/${id}`, params);
+  }
+
+  /**
+   * List all invoices
+   */
+  async list(options?: InvoiceListOptions): Promise<StripeList<Invoice>> {
+    return this.client.get<StripeList<Invoice>>('/invoices', options as Record<string, string | number | boolean | undefined>);
+  }
+
+  /**
+   * Delete a draft invoice
+   */
+  async del(id: string): Promise<DeletedObject> {
+    return this.client.delete<DeletedObject>(`/invoices/${id}`);
+  }
+
+  /**
+   * Finalize an invoice
+   */
+  async finalize(id: string, params?: InvoiceFinalizeParams): Promise<Invoice> {
+    return this.client.post<Invoice>(`/invoices/${id}/finalize`, params || {});
+  }
+
+  /**
+   * Pay an invoice
+   */
+  async pay(id: string, params?: InvoicePayParams): Promise<Invoice> {
+    return this.client.post<Invoice>(`/invoices/${id}/pay`, params || {});
+  }
+
+  /**
+   * Send an invoice for manual payment
+   */
+  async send(id: string): Promise<Invoice> {
+    return this.client.post<Invoice>(`/invoices/${id}/send`, {});
+  }
+
+  /**
+   * Void an invoice
+   */
+  async void(id: string): Promise<Invoice> {
+    return this.client.post<Invoice>(`/invoices/${id}/void`, {});
+  }
+
+  /**
+   * Mark an invoice as uncollectible
+   */
+  async markUncollectible(id: string): Promise<Invoice> {
+    return this.client.post<Invoice>(`/invoices/${id}/mark_uncollectible`, {});
+  }
+
+  /**
+   * Search invoices
+   * Query syntax: https://stripe.com/docs/search#query-fields-for-invoices
+   */
+  async search(query: string, options?: { limit?: number; page?: string }): Promise<StripeSearchResult<Invoice>> {
+    return this.client.get<StripeSearchResult<Invoice>>('/invoices/search', {
+      query,
+      limit: options?.limit,
+      page: options?.page,
+    });
+  }
+}

package/connectors/connect-stripe/src/api/payment-intents.ts

@@ -0,0 +1,81 @@
+import type { ConnectorClient } from './client';
+import type {
+  PaymentIntent,
+  PaymentIntentCreateParams,
+  PaymentIntentUpdateParams,
+  PaymentIntentConfirmParams,
+  PaymentIntentCancelParams,
+  PaymentIntentCaptureParams,
+  PaymentIntentListOptions,
+  StripeList,
+  StripeSearchResult,
+} from '../types';
+
+/**
+ * Stripe Payment Intents API
+ * https://stripe.com/docs/api/payment_intents
+ */
+export class PaymentIntentsApi {
+  constructor(private readonly client: ConnectorClient) {}
+
+  /**
+   * Create a payment intent
+   */
+  async create(params: PaymentIntentCreateParams): Promise<PaymentIntent> {
+    return this.client.post<PaymentIntent>('/payment_intents', params);
+  }
+
+  /**
+   * Retrieve a payment intent by ID
+   */
+  async get(id: string, options?: { client_secret?: string }): Promise<PaymentIntent> {
+    return this.client.get<PaymentIntent>(`/payment_intents/${id}`, options);
+  }
+
+  /**
+   * Update a payment intent
+   */
+  async update(id: string, params: PaymentIntentUpdateParams): Promise<PaymentIntent> {
+    return this.client.post<PaymentIntent>(`/payment_intents/${id}`, params);
+  }
+
+  /**
+   * List all payment intents
+   */
+  async list(options?: PaymentIntentListOptions): Promise<StripeList<PaymentIntent>> {
+    return this.client.get<StripeList<PaymentIntent>>('/payment_intents', options as Record<string, string | number | boolean | undefined>);
+  }
+
+  /**
+   * Confirm a payment intent
+   */
+  async confirm(id: string, params?: PaymentIntentConfirmParams): Promise<PaymentIntent> {
+    return this.client.post<PaymentIntent>(`/payment_intents/${id}/confirm`, params || {});
+  }
+
+  /**
+   * Cancel a payment intent
+   */
+  async cancel(id: string, params?: PaymentIntentCancelParams): Promise<PaymentIntent> {
+    return this.client.post<PaymentIntent>(`/payment_intents/${id}/cancel`, params || {});
+  }
+
+  /**
+   * Capture a payment intent (for manual capture)
+   */
+  async capture(id: string, params?: PaymentIntentCaptureParams): Promise<PaymentIntent> {
+    return this.client.post<PaymentIntent>(`/payment_intents/${id}/capture`, params || {});
+  }
+
+  /**
+   * Search payment intents
+   * Query syntax: https://stripe.com/docs/search#query-fields-for-payment-intents
+   */
+  async search(query: string, options?: { limit?: number; page?: string }): Promise<StripeSearchResult<PaymentIntent>> {
+    return this.client.get<StripeSearchResult<PaymentIntent>>('/payment_intents/search', {
+      query,
+      limit: options?.limit,
+      page: options?.page,
+    });
+  }
+}