Server and browser clients, every method, Funnel/Paywall/experiment entry points and error handling.
npm install --save-exact @tinkerlandai/indiana-sdk@0.6.2One package serves Node.js 22+ backends and browsers and ships TypeScript types. Every client defaults to https://api.tinker.cash; set baseUrl explicitly for a test service. See the install page for every entry point.
Related: Install SDKs and CLI
createIndianaServer uses a Server Key and can only be created on a trusted backend; calling it in a browser throws SERVER_ONLY. Each method maps to one HTTP operation, and requests and responses are validated against the public contract.
import { createIndianaServer, IndianaError } from "@tinkerlandai/indiana-sdk/server"; const indiana = createIndianaServer({ baseUrl: process.env.INDIANA_API_URL!, apiKey: process.env.INDIANA_API_KEY!, scope: { projectId: process.env.INDIANA_PROJECT_ID!, environment: "sandbox" },}); export async function generateImage(verifiedUserId: string, eventId: string) { const { customer } = await indiana.getOrCreateCustomer({ externalUserId: verifiedUserId, }); const { check } = await indiana.checkEntitlement({ customerId: customer.id, requirement: { internal_feature_id: process.env.INDIANA_FEATURE_ID!, quantity: "1", properties: {}, }, }); if (!check.allowed) return { allowed: false as const }; try { const { receipts } = await indiana.trackUsage({ customerId: customer.id, // eventId is persisted before the call and reused on every retry. command: { eventName: "image_generated", quantity: "1", idempotencyKey: eventId }, }); for (const receipt of receipts) if (!receipt.accepted) console.warn("usage refused", receipt.reason); return { allowed: true as const, receipts }; } catch (error) { if (error instanceof IndianaError) console.error(error.code, error.recovery, error.requestId); throw error; }}| Area | Methods |
|---|---|
| Customers, Guests and Sessions | getOrCreateCustomer, getCustomer, listCustomers, updateCustomer, createCustomerSession, renewCustomerSession, revokeCustomerSessions, createGuestCustomer, resumeGuestSession, claimGuestCustomer |
| Entitlements and product presentation | checkEntitlement, resolveOffering, resolvePaywall, readHoldings |
| Balances, usage and ledger | readBalanceSource, adjustBalance, readUsage, setUsage, manageBalanceGrant, listBalanceGrants, manageUsageEntity, readUsageAnalytics, readCreditAnalytics, submitUsageBatch, readUsageBatch, readLedger, readCreditStatement, quoteBalance, trackUsage, mutateBalance |
| Seats | readSeats, manageSeat |
| Subscriptions and payments | setupPayment, readPaymentSetup, verifySubscriptions, previewAttach, attach, readSubscriptionOperation, previewUpdate, update, readSubscriptionUpdate, listSubscriptions, listPurchases, listSubscriptionConflicts, retrySubscriptionConflict, manageSubscriptionTrial, readSubscriptionTrial |
| Invoices, refunds and billing | listInvoiceTemplates, previewInvoice, createInvoice, manageInvoice, readInvoiceOperation, listInvoices, getInvoice, previewRefund, refund, readRefund, manageBillingLimits, readBillingInvoice |
| Coupons, rewards and referrals | grantOffer, recordCouponRedemption |
| Features, evaluation and events | getFeatures, evaluateFeatures, trackEvents |
| Native purchases | restoreNativePurchase |
| AI pricing | readAiPricing |
Server methods by area
Customers, Guests and Sessions
getOrCreateCustomer, getCustomer, listCustomers, updateCustomer, createCustomerSession, renewCustomerSession, revokeCustomerSessions, createGuestCustomer, resumeGuestSession, claimGuestCustomerEntitlements and product presentation
checkEntitlement, resolveOffering, resolvePaywall, readHoldingsBalances, usage and ledger
readBalanceSource, adjustBalance, readUsage, setUsage, manageBalanceGrant, listBalanceGrants, manageUsageEntity, readUsageAnalytics, readCreditAnalytics, submitUsageBatch, readUsageBatch, readLedger, readCreditStatement, quoteBalance, trackUsage, mutateBalanceSeats
readSeats, manageSeatSubscriptions and payments
setupPayment, readPaymentSetup, verifySubscriptions, previewAttach, attach, readSubscriptionOperation, previewUpdate, update, readSubscriptionUpdate, listSubscriptions, listPurchases, listSubscriptionConflicts, retrySubscriptionConflict, manageSubscriptionTrial, readSubscriptionTrialInvoices, refunds and billing
listInvoiceTemplates, previewInvoice, createInvoice, manageInvoice, readInvoiceOperation, listInvoices, getInvoice, previewRefund, refund, readRefund, manageBillingLimits, readBillingInvoiceCoupons, rewards and referrals
grantOffer, recordCouponRedemptionFeatures, evaluation and events
getFeatures, evaluateFeatures, trackEventsNative purchases
restoreNativePurchaseAI pricing
readAiPricing| Option | Description |
|---|---|
apiKey | Server Key (gg_sk_) from your backend secret store. |
scope | { projectId, environment }: the App UUID and sandbox or live, matching the Key. |
baseUrl | API origin, default https://api.tinker.cash; without /api/v1. |
timeoutMs | Per-request timeout, default 10000, maximum 120000. |
fetch | Inject a custom fetch for proxies or offline tests. |
Client options
apiKey
gg_sk_) from your backend secret store.scope
{ projectId, environment }: the App UUID and sandbox or live, matching the Key.baseUrl
timeoutMs
fetch
Browsers never hold a Server Key. After your backend verifies the login it issues a Customer Token, and the browser calls identify(token). The token determines the Customer; a browser cannot select another customerId. Call reset() on sign-out or account switch.
import { createIndianaServer } from "@tinkerlandai/indiana-sdk/server"; const indiana = createIndianaServer({ baseUrl: process.env.INDIANA_API_URL!, apiKey: process.env.INDIANA_API_KEY!, scope: { projectId: process.env.INDIANA_PROJECT_ID!, environment: "sandbox" },}); // Call only after your own login check succeeds.export async function issueCustomerToken(verifiedUserId: string) { const { customer } = await indiana.getOrCreateCustomer({ externalUserId: verifiedUserId, }); const { customerToken, expiresAt } = await indiana.createCustomerSession(customer.id); return { customerToken, expiresAt };}| Area | Methods |
|---|---|
| Entitlements and product presentation | checkEntitlement, resolveOffering, resolvePaywall, readHoldings |
| Balances, usage and ledger | readLedger, readCreditStatement, quoteBalance |
| Subscriptions and payments | setupPayment, readPaymentSetup, previewAttach, attach, readSubscriptionOperation, previewUpdate, update, readSubscriptionUpdate |
| Invoices, refunds and billing | readBillingControls, prepareBillingAuthorization, confirmBillingAuthorization, setBillingCoupons, revokeBillingAuthorization, listBillingInvoices, readBillingInvoice |
| Coupons, rewards and referrals | redeemCoupon, listOffers, claimCoupon, redeemReward, createReferralCode |
| Features, evaluation and events | features, track, flush |
| Native purchases | restoreNativePurchase |
Browser methods by area
Entitlements and product presentation
checkEntitlement, resolveOffering, resolvePaywall, readHoldingsBalances, usage and ledger
readLedger, readCreditStatement, quoteBalanceSubscriptions and payments
setupPayment, readPaymentSetup, previewAttach, attach, readSubscriptionOperation, previewUpdate, update, readSubscriptionUpdateInvoices, refunds and billing
readBillingControls, prepareBillingAuthorization, confirmBillingAuthorization, setBillingCoupons, revokeBillingAuthorization, listBillingInvoices, readBillingInvoiceCoupons, rewards and referrals
redeemCoupon, listOffers, claimCoupon, redeemReward, createReferralCodeFeatures, evaluation and events
features, track, flushNative purchases
restoreNativePurchasesessions:create plus the scopes the browser will use, such as entitlements:read, billing:write or offers:resolve.indiana.forFunnel({ funnelId, versionId }) returns a resource client bound to that Funnel for coupon claims, Offering/Paywall resolution and purchase quotes.| Function | Entry | Purpose |
|---|---|---|
createFunnelStartClient | /server | Start a Funnel Run from your backend and receive a Run Token |
createFunnelRunController, showFunnelRun | main | Display and advance a Run in the browser |
createFunnelClient | main | Start a Run from a client that holds a Customer Token |
createLocalFunnelClient, createConfigurationSync | main / /server | Local-mode Funnels and shared public configuration |
createFunnelDecisionClient, createFunnelCampaignClient | /server | Server decisions, Campaign starts and adoption reports |
createFunnelOrchestrationClient, renewFunnelRun | /server | Signal a Run, read its results and rotate its Run Token |
createPaywallStartClient, createPaywallSession, showPaywall | /server / main | Standalone Paywall sessions and display |
createFeatureClient, indiana.features() | main | Feature evaluation and subscriptions |
createPageExperiments | /page | URL redirect experiments |
createVisualExperiments | /visual | Visual experiments |
createNativeReceiptClient | /server | Submit native store proofs from your backend |
createAiUsageMiddleware, createAiPricing | /server | AI SDK usage-billing middleware and pricing |
createOpenRouterUsageClient, trackOpenRouterUsage | /openrouter | OpenRouter usage billing |
Other exports
createFunnelStartClient
/servercreateFunnelRunController, showFunnelRun
createFunnelClient
createLocalFunnelClient, createConfigurationSync
/servercreateFunnelDecisionClient, createFunnelCampaignClient
/servercreateFunnelOrchestrationClient, renewFunnelRun
/servercreatePaywallStartClient, createPaywallSession, showPaywall
/server / maincreateFeatureClient, indiana.features()
createPageExperiments
/pagecreateVisualExperiments
/visualcreateNativeReceiptClient
/servercreateAiUsageMiddleware, createAiPricing
/servercreateOpenRouterUsageClient, trackOpenRouterUsage
/openrouterRelated: Run Funnels·Payments, subscriptions and billing·Features, experiments and events
Failures throw IndianaError with code, status, requestId, retryable, recovery, and optional reason and retryAfterSeconds. The SDK never retries writes automatically: persist the requestId, eventId or idempotencyKey before sending, and after an unknown result replay the same value and input or read the original operation.
Related: Error codes and recovery