@nestuge/sdk 0.1.0

package/dist/index.d.cts

@@ -0,0 +1,560 @@
+type FetchLike = (input: string, init: RequestInit) => Promise<Response>;
+interface RequestorConfig {
+    apiKey: string;
+    baseUrl: string;
+    maxRetries: number;
+    timeoutMs: number;
+    fetch: FetchLike;
+}
+interface RequestOptions {
+    method: 'GET' | 'POST' | 'PATCH' | 'DELETE';
+    /** Contract path, e.g. `/v1/customers/{id}` with params already interpolated. */
+    path: string;
+    /** Shallow object of query params; undefined values are omitted. */
+    query?: object;
+    body?: unknown;
+}
+declare class Requestor {
+    private readonly config;
+    constructor(config: RequestorConfig);
+    /** Performs a request against the Dev API and returns the unwrapped `data`. */
+    request<T>(options: RequestOptions): Promise<T>;
+    private buildUrl;
+    private dispatch;
+}
+
+/** Whether the API key (and therefore the request) is live or test mode. */
+type Mode = 'live' | 'test';
+/** One page of a cursor-paginated list. */
+interface Page<T> {
+    items: T[];
+    hasMore: boolean;
+    nextCursor: string | null;
+}
+/** Standard cursor-pagination query parameters. */
+interface ListParams {
+    /** Page size, 1–100. Defaults to 20 on the server. */
+    limit?: number;
+    /** Opaque cursor from a prior page's `nextCursor`. Omit for the first page. */
+    cursor?: string;
+}
+/** Response of `nestuge.ping()`. */
+interface PingResponse {
+    ok: boolean;
+    brandID: string;
+    mode: Mode;
+    scopes: string[];
+}
+
+/** A hub member (membership) of the brand. */
+interface Customer {
+    membershipId: string;
+    name: string;
+    email: string;
+    phone: string | null;
+    hubID: string;
+    status: string;
+    plan: string;
+    joinedAt: string;
+}
+interface CustomerListParams extends ListParams {
+    /** Restrict results to a single hub. */
+    hubID?: string;
+}
+
+declare class Customers {
+    private readonly requestor;
+    constructor(requestor: Requestor);
+    /** Lists the brand's hub members, newest first. Requires `customers:read`. */
+    list(params?: CustomerListParams): Promise<Page<Customer>>;
+    /** Returns a single hub membership by its membership id. */
+    retrieve(id: string): Promise<Customer>;
+    /** Iterates every customer, following pagination cursors automatically. */
+    iterate(params?: Omit<CustomerListParams, 'cursor'>): AsyncGenerator<Customer>;
+}
+
+/** A hub community/calendar event. */
+interface HubEvent {
+    id: string;
+    hubID: string;
+    hubName: string;
+    title: string;
+    description?: string;
+    date: string;
+    endDate?: string;
+    time?: {
+        start?: string;
+        end?: string;
+    };
+    timezone?: string;
+    type?: string;
+    venue?: string | null;
+    meetLink?: string;
+    attendeeStatus?: string;
+}
+interface CreateEventParams {
+    /** The hub to create the event in. Must belong to the authenticated brand. */
+    hubID: string;
+    title: string;
+    description: string;
+    /** ISO 8601 date. */
+    date: string;
+    endDate?: string;
+    time: {
+        start: string;
+        end: string;
+    };
+    timezone?: string;
+    type: string;
+    venue?: string | null;
+    meetLink?: string;
+    audience?: string;
+    tier?: string | null;
+    targetedGroupIDs?: string[];
+    isAllDay?: boolean;
+    repeat?: string;
+    reminder: string;
+    color: string;
+    sendNotification: boolean;
+}
+
+declare class Events {
+    private readonly requestor;
+    constructor(requestor: Requestor);
+    /** Lists the brand's hub community events, newest first. Requires `events:read`. */
+    list(params?: ListParams): Promise<Page<HubEvent>>;
+    /** Returns a single hub event owned by the brand. */
+    retrieve(id: string): Promise<HubEvent>;
+    /**
+     * Creates a hub event in one of the brand's hubs. Requires `events:write`
+     * and the brand to have Google Calendar connected.
+     */
+    create(params: CreateEventParams): Promise<HubEvent>;
+    /** Iterates every event, following pagination cursors automatically. */
+    iterate(): AsyncGenerator<HubEvent>;
+}
+
+interface ProductEventDetails {
+    eventType: string | null;
+    venue: string | null;
+    dateTime: string | null;
+    endDate: string | null;
+}
+interface Product {
+    id: string;
+    type: string;
+    status: string;
+    title: string;
+    description: string;
+    imageUrl: string | null;
+    url: string;
+    visibility: string | null;
+    isFree: boolean;
+    keywords: string[];
+    createdAt: string;
+    updatedAt: string;
+    event: ProductEventDetails | null;
+}
+interface Money {
+    amount: number;
+    /** ISO 4217 code, e.g. "NGN". */
+    currency: string;
+}
+/** A pricing tier (payment plan) of a product. */
+interface ProductTier {
+    id: string;
+    name: string;
+    /** Plan type, e.g. "onetime", "recurring", "installment". */
+    type: string | null;
+    price: Money;
+    discount: Money | null;
+    recurrence: {
+        /** Billing period, e.g. "monthly", "yearly". */
+        periodic: string;
+        count: number | null;
+        interval: number | null;
+    } | null;
+    perks: string[];
+    buttonText: string | null;
+    /** ISO 8601 date-time the tier stops being purchasable, if set. */
+    timeBound: string | null;
+    /** Total purchasable slots, if capped. */
+    slots: number | null;
+    noOfTickets: number | null;
+    /** IDs of the product items this tier grants access to. */
+    itemIDs: string[];
+    isDefault: boolean;
+    status: string | null;
+    archived: boolean;
+}
+/**
+ * A content item attached to a product. Descriptive fields only — the
+ * deliverable itself (links, files) is never exposed through the API.
+ */
+interface ProductItem {
+    id: string;
+    type: string | null;
+    title: string;
+    description: string | null;
+    image: string | null;
+    duration: number | null;
+    isAddon: boolean;
+    parentId: string | null;
+    price: Money | null;
+}
+/** Returned by `products.retrieve`: the product plus its tiers and items. */
+interface ProductDetail extends Product {
+    tiers: ProductTier[];
+    items: ProductItem[];
+}
+type ProductType = 'custom' | 'event' | 'booking';
+type ProductVisibility = 'public' | 'private' | 'invite-only';
+type ProductEventType = 'Zoom' | 'Online' | 'In-Person' | 'Google Meet';
+interface CreateProductParams {
+    type: ProductType;
+    /** 6–80 characters. */
+    title: string;
+    description: string;
+    /** HTTPS URL. */
+    imageUrl: string;
+    visibility?: ProductVisibility;
+    /** Set `isFree: true` or provide `price` — exactly one of the two. */
+    isFree?: boolean;
+    price?: {
+        amount: number;
+        /** ISO 4217 code, e.g. "NGN". */
+        currency: string;
+    };
+    /** Max 300 characters. */
+    refundPolicy?: string;
+    /** Required when `type` is `event`. `venue` is required for In-Person events. */
+    event?: {
+        eventType: ProductEventType;
+        /** ISO 8601 date-time. */
+        dateTime: string;
+        venue?: string | null;
+        endDate?: string | null;
+    };
+    /** Required when `type` is `booking`. */
+    booking?: {
+        /** Minutes, minimum 15. */
+        bookingDuration: number;
+        /** IANA timezone, e.g. "Africa/Lagos". */
+        timezone: string;
+    };
+}
+
+declare class Products {
+    private readonly requestor;
+    constructor(requestor: Requestor);
+    /** Lists the brand's products (all types), newest first. Requires `products:read`. */
+    list(params?: ListParams): Promise<Page<Product>>;
+    /**
+     * Returns a single product owned by the brand, including its pricing
+     * tiers and content items.
+     */
+    retrieve(id: string): Promise<ProductDetail>;
+    /**
+     * Creates a draft product. Requires `products:write`. Test-mode keys
+     * validate and return a preview without persisting.
+     */
+    create(params: CreateProductParams): Promise<Product>;
+    /** Iterates every product, following pagination cursors automatically. */
+    iterate(): AsyncGenerator<Product>;
+}
+
+interface Purchase {
+    id: string;
+    productId: string;
+    title: string;
+    status: string;
+    productType: string | null;
+    planName: string | null;
+    customer: {
+        name: string;
+        email: string;
+    };
+    country: string | null;
+    paid: boolean;
+    purchasedOn: string;
+    ticketID: string | null;
+    certificateID: string | null;
+}
+
+declare class Purchases {
+    private readonly requestor;
+    constructor(requestor: Requestor);
+    /** Lists the brand's purchases/orders, newest first. Requires `purchases:read`. */
+    list(params?: ListParams): Promise<Page<Purchase>>;
+    /** Returns a single purchase/order by id. */
+    retrieve(id: string): Promise<Purchase>;
+    /** Iterates every purchase, following pagination cursors automatically. */
+    iterate(): AsyncGenerator<Purchase>;
+}
+
+interface Ticket {
+    ticketID: string;
+    eventName: string;
+    ticketName: string | null;
+    date: string | null;
+    venue: string | null;
+    purchaseID: string;
+    attendee: {
+        name: string;
+        email: string;
+    };
+    isCheckedIn: boolean;
+    checkinTime: string | null;
+}
+
+declare class Tickets {
+    private readonly requestor;
+    constructor(requestor: Requestor);
+    /** Returns a single event ticket by ticket id. Requires `purchases:read`. */
+    retrieve(id: string): Promise<Ticket>;
+    /**
+     * Checks in an event attendee by ticket id. Requires `purchases:write`.
+     * Test-mode keys validate and return the checked-in ticket without persisting.
+     */
+    checkIn(id: string): Promise<Ticket>;
+}
+
+interface Transaction {
+    /** Transaction reference — also the id used with `transactions.retrieve()`. */
+    txref: string;
+    type: string;
+    status: string;
+    amount: number;
+    currency: string;
+    customer: {
+        name: string;
+        email: string;
+    };
+    createdAt: string;
+    resourceID: string | null;
+}
+
+declare class Transactions {
+    private readonly requestor;
+    constructor(requestor: Requestor);
+    /** Lists the brand's transactions, newest first. Requires `transactions:read`. */
+    list(params?: ListParams): Promise<Page<Transaction>>;
+    /** Returns a single transaction by its reference (`txref`). */
+    retrieve(id: string): Promise<Transaction>;
+    /** Iterates every transaction, following pagination cursors automatically. */
+    iterate(): AsyncGenerator<Transaction>;
+}
+
+type WebhookEventType = 'transaction.succeeded' | 'transaction.failed' | 'payout.settled' | 'subscription.renewed' | 'subscription.expired' | 'subscription.completed' | 'member.joined' | 'member.removed';
+type WebhookEndpointStatus = 'active' | 'disabled';
+interface WebhookEndpoint {
+    id: string;
+    url: string;
+    events: WebhookEventType[];
+    status: WebhookEndpointStatus;
+    description: string | null;
+    createdAt: string;
+    updatedAt: string;
+}
+/**
+ * Returned only by `webhooks.create()`. The `signingSecret` is shown once and
+ * can never be retrieved again — store it securely.
+ */
+interface WebhookEndpointWithSecret extends WebhookEndpoint {
+    signingSecret: string;
+}
+interface CreateWebhookParams {
+    /** HTTPS URL to deliver events to. */
+    url: string;
+    /** At least one event type. */
+    events: WebhookEventType[];
+    /** Max 200 characters. */
+    description?: string;
+}
+interface UpdateWebhookParams {
+    url?: string;
+    events?: WebhookEventType[];
+    status?: WebhookEndpointStatus;
+    description?: string | null;
+}
+interface TestWebhookParams {
+    eventType: WebhookEventType;
+    /** Limit the test delivery to a single endpoint. */
+    endpointID?: string;
+}
+type WebhookResourceType = 'transaction' | 'purchase' | 'member';
+type WebhookDeliveryStatus = 'pending' | 'success' | 'failed';
+interface WebhookDelivery {
+    id: string;
+    endpointID: string;
+    eventType: WebhookEventType;
+    resourceType: WebhookResourceType;
+    resourceID: string;
+    status: WebhookDeliveryStatus;
+    attempts: number;
+    responseCode: number | null;
+    mode: Mode;
+    createdAt: string;
+    deliveredAt: string | null;
+}
+/**
+ * The JSON body Nestuge POSTs to your webhook endpoint, discriminated on
+ * `type` so `data` narrows to the right resource shape.
+ */
+type WebhookEvent = WebhookEventOf<'transaction.succeeded', Transaction> | WebhookEventOf<'transaction.failed', Transaction> | WebhookEventOf<'payout.settled', Transaction> | WebhookEventOf<'subscription.renewed', Purchase> | WebhookEventOf<'subscription.expired', Purchase> | WebhookEventOf<'subscription.completed', Purchase> | WebhookEventOf<'member.joined', Customer> | WebhookEventOf<'member.removed', Customer>;
+interface WebhookEventOf<T extends WebhookEventType, D> {
+    /** Delivery id (`X-Nestuge-Delivery` carries the same value). */
+    id: string;
+    type: T;
+    /** ISO 8601 creation time of the event. */
+    created: string;
+    data: D;
+}
+
+declare const SIGNATURE_HEADER = "X-Nestuge-Signature";
+interface VerifySignatureParams {
+    /** The raw, unmodified request body string (not re-serialized JSON). */
+    payload: string;
+    /** Value of the `X-Nestuge-Signature` header (`sha256=<hex>`). */
+    signature: string;
+    /** The endpoint's signing secret, returned once by `webhooks.create()`. */
+    secret: string;
+}
+/** Verifies a webhook signature with a timing-safe HMAC-SHA256 comparison. */
+declare const verifySignature: ({ payload, signature, secret, }: VerifySignatureParams) => Promise<boolean>;
+/**
+ * Verifies the signature and parses the payload into a typed `WebhookEvent`.
+ * Throws `WebhookVerificationError` on a bad signature or unparseable body.
+ */
+declare const constructEvent: (params: VerifySignatureParams) => Promise<WebhookEvent>;
+
+/** All webhook endpoints require the `webhooks:write` scope. */
+declare class Webhooks {
+    private readonly requestor;
+    readonly deliveries: WebhookDeliveries;
+    constructor(requestor: Requestor);
+    /**
+     * Registers an HTTPS endpoint URL. The returned `signingSecret` is shown
+     * once in this response and can never be retrieved again.
+     */
+    create(params: CreateWebhookParams): Promise<WebhookEndpointWithSecret>;
+    /** Lists the brand's webhook endpoints. */
+    list(params?: ListParams): Promise<Page<WebhookEndpoint>>;
+    /** Returns a single webhook endpoint. */
+    retrieve(id: string): Promise<WebhookEndpoint>;
+    /** Updates a webhook endpoint's URL, events, status, or description. */
+    update(id: string, params: UpdateWebhookParams): Promise<WebhookEndpoint>;
+    /** Deletes a webhook endpoint. */
+    del(id: string): Promise<{
+        id: string;
+        deleted: boolean;
+    }>;
+    /**
+     * Synthesizes a sample event and delivers it through the real
+     * signed/retried/logged pipeline as a test-mode delivery.
+     */
+    test(params: TestWebhookParams): Promise<{
+        created: number;
+    }>;
+    /** Iterates every webhook endpoint, following pagination cursors automatically. */
+    iterate(): AsyncGenerator<WebhookEndpoint>;
+    /**
+     * Verifies an incoming webhook's `X-Nestuge-Signature` header with a
+     * timing-safe HMAC-SHA256 comparison over the raw request body.
+     */
+    verifySignature(params: VerifySignatureParams): Promise<boolean>;
+    /**
+     * Verifies the signature and returns the parsed, typed event. Throws
+     * `WebhookVerificationError` if verification fails.
+     */
+    constructEvent(params: VerifySignatureParams): Promise<WebhookEvent>;
+}
+declare class WebhookDeliveries {
+    private readonly requestor;
+    constructor(requestor: Requestor);
+    /** Lists webhook delivery attempts, newest first. */
+    list(params?: ListParams): Promise<Page<WebhookDelivery>>;
+    /** Returns a single delivery record. */
+    retrieve(id: string): Promise<WebhookDelivery>;
+    /** Re-queues a delivery as a fresh attempt; the original record is preserved. */
+    resend(id: string): Promise<WebhookDelivery>;
+    /** Iterates every delivery record, following pagination cursors automatically. */
+    iterate(): AsyncGenerator<WebhookDelivery>;
+}
+
+interface NestugeConfig {
+    /** Brand API key (`nk_live_…` or `nk_test_…`) from Settings → Developer. */
+    apiKey: string;
+    /** API origin. Defaults to `https://nestuge.com`. */
+    baseUrl?: string;
+    /** Extra retry attempts on 429/5xx/network errors. Defaults to 2. */
+    maxRetries?: number;
+    /** Per-attempt timeout in milliseconds. Defaults to 30000. */
+    timeoutMs?: number;
+    /** Custom fetch implementation (testing, proxies). Defaults to global fetch. */
+    fetch?: FetchLike;
+}
+declare class Nestuge {
+    readonly customers: Customers;
+    readonly products: Products;
+    readonly purchases: Purchases;
+    readonly transactions: Transactions;
+    readonly events: Events;
+    readonly tickets: Tickets;
+    readonly webhooks: Webhooks;
+    private readonly requestor;
+    constructor(config: NestugeConfig);
+    /**
+     * Authenticated health check: confirms the key works and returns the
+     * resolved brand, key mode, and granted scopes. No scope required.
+     */
+    ping(): Promise<PingResponse>;
+}
+
+interface ErrorContext {
+    message: string;
+    /** HTTP status code, when the server responded. */
+    status?: number;
+    /** The `code` field from the API error envelope. */
+    code?: number;
+    /** The `error` field from the API error envelope (detail text). */
+    detail?: string;
+}
+/** Base class for every error thrown by the SDK. */
+declare class NestugeError extends Error {
+    readonly status?: number;
+    readonly code?: number;
+    readonly detail?: string;
+    constructor(context: ErrorContext);
+}
+/** 400 — the request body or parameters failed validation. */
+declare class ValidationError extends NestugeError {
+}
+/** 401 — missing, malformed, or revoked API key. */
+declare class AuthenticationError extends NestugeError {
+}
+/** 403 — the API key lacks a required scope for this endpoint. */
+declare class PermissionError extends NestugeError {
+}
+/** 404 — the resource does not exist or belongs to another brand. */
+declare class NotFoundError extends NestugeError {
+}
+/** 429 — rate limit exceeded (120 requests/minute per key). */
+declare class RateLimitError extends NestugeError {
+    /** Seconds to wait before retrying, from the `Retry-After` header. */
+    readonly retryAfter?: number;
+    constructor(context: ErrorContext & {
+        retryAfter?: number;
+    });
+}
+/** 5xx — the API failed to process the request. */
+declare class ServerError extends NestugeError {
+}
+/** The request never reached the API (network failure or timeout). */
+declare class ConnectionError extends NestugeError {
+}
+/** Webhook signature verification failed in `constructEvent`. */
+declare class WebhookVerificationError extends NestugeError {
+}
+
+export { AuthenticationError, ConnectionError, type CreateEventParams, type CreateProductParams, type CreateWebhookParams, type Customer, type CustomerListParams, type HubEvent, type ListParams, type Mode, type Money, Nestuge, type NestugeConfig, NestugeError, NotFoundError, type Page, PermissionError, type PingResponse, type Product, type ProductDetail, type ProductEventDetails, type ProductEventType, type ProductItem, type ProductTier, type ProductType, type ProductVisibility, type Purchase, RateLimitError, SIGNATURE_HEADER, ServerError, type TestWebhookParams, type Ticket, type Transaction, type UpdateWebhookParams, ValidationError, type VerifySignatureParams, type WebhookDelivery, type WebhookDeliveryStatus, type WebhookEndpoint, type WebhookEndpointStatus, type WebhookEndpointWithSecret, type WebhookEvent, type WebhookEventType, type WebhookResourceType, WebhookVerificationError, constructEvent, Nestuge as default, verifySignature };