Configuration

interface DarajaConfig {
  consumerKey: string;
  consumerSecret: string;
  environment?: "sandbox" | "production"; // default: 'sandbox'
  timeout?: number; // default: 10000 (ms)
}

consumerKey / consumerSecret

Required. Both go through a validation pipeline the moment you call Daraja(config) before any network request is made:

1. Presence not undefined, null, or ""
2. Type must be a string
3. Sanitization surrounding quotes, tabs, and newlines picked up from .env copy-paste are stripped automatically
4. Placeholder detection values like "YOUR_CONSUMER_KEY", "changeme", or "xxxx..." are rejected outright
5. No internal whitespace
6. Alphanumeric only
7. Exact length 48 characters for the Consumer Key, 64 for the Consumer Secret
8. Cross-check if consumerKey === consumerSecret, or if one field's length matches what the other field is supposed to be, the error message tells you that you likely swapped them

// Throws: "Consumer Key must be exactly 48 characters (received 64, 16
// characters too long). This matches the expected length of the other
// credential. Did you swap Consumer Key and Consumer Secret?"
Daraja({
  consumerKey: process.env.DARAJA_CONSUMER_SECRET!, // oops
  consumerSecret: process.env.DARAJA_CONSUMER_KEY!,
});

environment

• 'sandbox' (default) points at https://sandbox.safaricom.co.ke
• 'production' points at https://api.safaricom.co.ke, and additionally requires HTTPS on every callback URL (callBackURL, confirmationUrl, validationUrl, queueTimeOutURL, resultURL). Passing an http:// callback URL in production throws INVALID_CALLBACK_URL immediately instead of letting Daraja reject it later.

Any value outside 'sandbox' / 'production' throws INVALID_ENVIRONMENT at construction time.

timeout

Milliseconds before an in-flight request is aborted via AbortController. Applies to every HTTP call the SDK makes, including the OAuth token fetch. Must be a positive, finite number 0, negative numbers, NaN, and Infinity all throw INVALID_TIMEOUT.

Aborted requests surface as a DarajaError with errorCode: 'REQUEST_TIMEOUT', not a raw AbortError so your error handling only needs to know about one error shape. See Error Handling.

Full example

import { Daraja } from "@lumierelabs/daraja";

export const daraja = Daraja({
  consumerKey: process.env.DARAJA_CONSUMER_KEY!,
  consumerSecret: process.env.DARAJA_CONSUMER_SECRET!,
  environment: process.env.NODE_ENV === "production" ? "production" : "sandbox",
  timeout: 15000,
});