@timbrix/sdk 0.1.0

package/dist/index.d.ts

@@ -0,0 +1,684 @@
+import { KyInstance, Options } from 'ky';
+
+type AuthMode = "bearer" | "apiKey";
+interface TimbrixConfig {
+    baseUrl?: string;
+    apiKey?: string;
+    bearerToken?: string;
+}
+interface TimbrixUser {
+    id: string;
+    email: string;
+    createdAt?: string;
+    updatedAt?: string;
+}
+interface LoginInput {
+    email: string;
+    password: string;
+}
+interface LoginResponse {
+    access_token: string;
+    user?: TimbrixUser;
+}
+interface Organization {
+    id: string;
+    name: string;
+    slug: string;
+    logo?: string | null;
+    plan: "free" | "pro" | "enterprise";
+    ownerId: string;
+    createdAt: string;
+    updatedAt: string;
+}
+interface CreateOrganizationInput {
+    name: string;
+    slug: string;
+    logo?: string;
+}
+interface UpdateOrganizationInput {
+    name?: string;
+    logo?: string;
+}
+interface OrganizationDetails {
+    id: string;
+    slug: string;
+    logo_url?: string;
+    timezone: string;
+    created_at: string;
+    updated_at: string;
+    is_production_ready: boolean;
+    pending_steps?: Array<{
+        type: string;
+        description: string;
+    }>;
+    legal: {
+        name?: string;
+        legal_name?: string;
+        tax_system?: string;
+        website?: string;
+        phone?: string;
+        rfc?: string;
+        zip?: string;
+        address?: {
+            street?: string;
+            exterior?: string;
+            interior?: string;
+            neighborhood?: string;
+            city?: string;
+            municipality?: string;
+            zip?: string;
+            state?: string;
+        };
+    };
+    customization: {
+        has_logo: boolean;
+        color?: string;
+        next_folio_number?: number;
+        next_folio_number_test?: number;
+        pdf_extra?: {
+            codes?: boolean;
+            address_codes?: boolean;
+            product_key?: boolean;
+            round_unit_price?: boolean;
+            tax_breakdown?: boolean;
+            ieps_breakdown?: boolean;
+            render_carta_porte?: boolean;
+            repeat_signature?: boolean;
+        };
+    };
+    certificate: {
+        has_certificate: boolean;
+        updated_at?: string;
+        expires_at?: string;
+        serial_number?: string;
+    };
+    fiel: {
+        has_fiel: boolean;
+        updated_at?: string;
+        expires_at?: string;
+        serial_number?: string;
+    };
+    receipts: {
+        periodicity?: string;
+        duration_days?: number;
+        next_folio_number?: number;
+        next_folio_number_test?: number;
+    };
+    self_invoice: {
+        allowed_cfdi_uses?: string[];
+        apply_resico_isr?: boolean;
+        support_email?: string;
+        support_email_verified?: boolean;
+    };
+}
+type OrganizationRole = "owner" | "admin" | "member";
+interface OrganizationMember {
+    id: string;
+    userId: string;
+    organizationId: string;
+    role: OrganizationRole;
+    user?: {
+        id: string;
+        email: string;
+    };
+    joinedAt?: string;
+    createdAt?: string;
+}
+interface OrganizationInvite {
+    id: string;
+    organizationId: string;
+    email: string;
+    role: Exclude<OrganizationRole, "owner">;
+    invitedById: string;
+    createdAt: string;
+    expiresAt?: string;
+}
+interface InviteMemberInput {
+    email: string;
+    role: "admin" | "member";
+}
+interface UpdateMemberRoleInput {
+    role: "admin" | "member";
+}
+interface LegalAddress {
+    street: string;
+    exterior: number;
+    interior?: number;
+    neighborhood: string;
+    city: string;
+    municipality: string;
+    zip: number;
+    state: string;
+}
+interface UpdateLegalDataInput {
+    name?: string;
+    legal_name?: string;
+    tax_system?: string;
+    website?: string;
+    support_email?: string;
+    phone?: string;
+    address?: LegalAddress;
+}
+interface ValidateCertificateResponse {
+    valid: boolean;
+    rfc?: string;
+    serialNumber?: string;
+    expiresAt?: string;
+    issuedAt?: string;
+    subjectName?: string;
+    isExpired?: boolean;
+    passwordValid?: boolean;
+    passwordError?: string;
+    error?: string;
+}
+type WebhookEvent = "organization.created" | "organization.updated" | "organization.deleted" | "member.added" | "member.removed" | "member.role_updated" | "invite.created" | "invite.accepted" | "invite.cancelled" | "oauth_app.created" | "oauth_app.revoked" | "webhook.created";
+interface Webhook {
+    id: string;
+    organizationId: string;
+    url: string;
+    events: WebhookEvent[];
+    isActive: boolean;
+    secret?: string;
+    createdAt: string;
+    updatedAt: string;
+}
+interface CreateWebhookInput {
+    url: string;
+    events: WebhookEvent[];
+}
+interface UpdateWebhookInput {
+    url?: string;
+    events?: WebhookEvent[];
+    isActive?: boolean;
+}
+interface WebhookDelivery {
+    id: string;
+    webhookId: string;
+    event: WebhookEvent;
+    statusCode: number;
+    responseBody: string;
+    attempts: number;
+    success: boolean;
+    createdAt: string;
+}
+type ApiKeyScope = "read:user" | "write:user" | "read:organization" | "write:organization" | "read:members" | "write:members" | "read:webhooks" | "write:webhooks" | "read:api-keys" | "write:api-keys";
+interface ApiKey {
+    id: string;
+    organizationId: string;
+    name: string;
+    description?: string | null;
+    keyPreview: string;
+    scopes: ApiKeyScope[];
+    isActive: boolean;
+    rateLimitPerMinute: number;
+    rateLimitPerHour: number;
+    allowedIps?: string[] | null;
+    expiresAt?: string | null;
+    lastUsedAt?: string | null;
+    usageCount: number;
+    createdBy: string;
+    createdAt: string;
+    updatedAt: string;
+}
+interface CreateApiKeyInput {
+    name: string;
+    description?: string;
+    scopes?: ApiKeyScope[];
+    rateLimitPerMinute?: number;
+    rateLimitPerHour?: number;
+    allowedIps?: string[];
+    expiresAt?: string;
+}
+interface CreateApiKeyResponse {
+    plainKey: string;
+    apiKey: Omit<ApiKey, "usageCount" | "lastUsedAt" | "createdBy" | "updatedAt">;
+}
+type UpdateApiKeyInput = Partial<CreateApiKeyInput>;
+interface ApiKeyStats {
+    totalRequests: number;
+    last24Hours: number;
+    last7Days: number;
+    last30Days: number;
+}
+interface ApiKeyValidateResponse {
+    valid: boolean;
+    keyId: string;
+    keyName: string;
+    organizationId: string;
+    scopes: ApiKeyScope[];
+    expiresAt?: string | null;
+    isActive: boolean;
+}
+interface CustomerAddress {
+    street: string;
+    exterior: string;
+    interior?: string | null;
+    neighborhood: string;
+    city: string;
+    municipality: string;
+    zip: string;
+    state: string;
+    country: string;
+}
+interface Customer {
+    id: string;
+    organizationId: string;
+    legalName: string;
+    taxId: string;
+    taxSystem: string;
+    email: string;
+    phone: string | null;
+    defaultInvoiceUse: string;
+    address: CustomerAddress;
+    createdAt: string;
+    updatedAt: string;
+}
+interface CreateCustomerInput {
+    legalName: string;
+    taxId: string;
+    taxSystem: string;
+    email: string;
+    phone?: string;
+    defaultInvoiceUse: string;
+    addressStreet: string;
+    addressExterior: string;
+    addressInterior?: string;
+    addressNeighborhood: string;
+    addressCity: string;
+    addressMunicipality: string;
+    addressZip: string;
+    addressState: string;
+    addressCountry?: string;
+}
+type UpdateCustomerInput = Partial<CreateCustomerInput>;
+type OAuthScope = "read:user" | "write:user" | "read:organization" | "write:organization" | "read:members" | "write:members" | "read:webhooks" | "write:webhooks" | "admin:organization" | "admin:all";
+interface OAuthApp {
+    clientId: string;
+    name: string;
+    description?: string | null;
+    redirectUri?: string | null;
+    scopes: OAuthScope[];
+    isActive: boolean;
+    createdBy: string;
+    createdAt: string;
+    updatedAt: string;
+}
+interface OAuthAppWithSecret extends OAuthApp {
+    clientSecret: string;
+}
+interface CreateOAuthAppInput {
+    name: string;
+    scopes: OAuthScope[];
+    description?: string;
+    redirectUri?: string;
+}
+type UpdateOAuthAppInput = Partial<Omit<CreateOAuthAppInput, "scopes"> & {
+    scopes?: OAuthScope[];
+    isActive?: boolean;
+}>;
+interface OAuthToken {
+    id: string;
+    clientId: string;
+    userId?: string | null;
+    scopes: OAuthScope[];
+    expiresAt: string;
+    createdAt: string;
+    lastUsedAt?: string | null;
+}
+interface TokenResponse {
+    access_token: string;
+    token_type: "Bearer";
+    expires_in: number;
+    scope: string;
+    refresh_token?: string;
+}
+interface GenerateTokenInput {
+    clientId: string;
+    clientSecret: string;
+    scopes: OAuthScope[];
+    userId?: string;
+}
+interface ExchangeCodeInput {
+    code: string;
+    clientId: string;
+    clientSecret: string;
+    redirectUri: string;
+    codeVerifier?: string;
+}
+interface RefreshTokenInput {
+    refreshToken: string;
+}
+interface ProductTax {
+    type: string;
+    rate: number;
+    withholding?: boolean;
+    factor?: string;
+}
+interface Product {
+    id: string;
+    organizationId: string;
+    livemode: boolean;
+    description: string;
+    productKey: number;
+    price: number;
+    taxIncluded: boolean;
+    taxability: string;
+    taxes: ProductTax[];
+    localTaxes: ProductTax[];
+    unitKey: string;
+    unitName: string;
+    sku: string | null;
+    createdAt: string;
+    updatedAt: string;
+}
+interface CreateProductInput {
+    description: string;
+    productKey: number;
+    price: number;
+    taxIncluded?: boolean;
+    taxability?: string;
+    taxes?: ProductTax[];
+    localTaxes?: ProductTax[];
+    unitKey?: string;
+    unitName?: string;
+    sku?: string;
+    livemode?: boolean;
+}
+type UpdateProductInput = Partial<CreateProductInput>;
+interface ListProductsFilters {
+    description?: string;
+    sku?: string;
+    productKey?: number;
+}
+interface TimbrixError {
+    statusCode: number;
+    message: string | string[];
+    error?: string;
+}
+
+declare class ApiKeysResource {
+    private http;
+    constructor(http: KyInstance);
+    /**
+     * List all API keys for an organization
+     */
+    list(organizationId: string): Promise<ApiKey[]>;
+    /**
+     * Get API key by ID
+     */
+    get(organizationId: string, apiKeyId: string): Promise<ApiKey>;
+    /**
+     * Create a new API key. The plain key is returned only once in the response.
+     */
+    create(organizationId: string, data: CreateApiKeyInput): Promise<CreateApiKeyResponse>;
+    /**
+     * Update API key
+     */
+    update(organizationId: string, apiKeyId: string, data: UpdateApiKeyInput): Promise<ApiKey>;
+    /**
+     * Delete (revoke) API key
+     */
+    delete(organizationId: string, apiKeyId: string): Promise<void>;
+    /**
+     * Get API key usage statistics for an organization
+     */
+    stats(organizationId: string): Promise<ApiKeyStats>;
+    /**
+     * Validate the currently authenticated API key (uses X-API-Key header)
+     */
+    validate(): Promise<ApiKeyValidateResponse>;
+}
+
+declare class AuthResource {
+    private http;
+    constructor(http: KyInstance);
+    /**
+     * Login with email and password. Returns an access token.
+     */
+    login(data: LoginInput): Promise<LoginResponse>;
+    /**
+     * Logout and revoke the current access token.
+     */
+    logout(): Promise<void>;
+}
+
+declare class CustomersResource {
+    private http;
+    constructor(http: KyInstance);
+    /**
+     * List all customers for an organization
+     */
+    list(organizationId: string): Promise<Customer[]>;
+    /**
+     * Get a customer by ID
+     */
+    get(organizationId: string, customerId: string): Promise<Customer>;
+    /**
+     * Create a new customer
+     */
+    create(organizationId: string, data: CreateCustomerInput): Promise<Customer>;
+    /**
+     * Update a customer
+     */
+    update(organizationId: string, customerId: string, data: UpdateCustomerInput): Promise<Customer>;
+    /**
+     * Delete a customer
+     */
+    delete(organizationId: string, customerId: string): Promise<void>;
+}
+
+declare class OAuthResource {
+    private http;
+    constructor(http: KyInstance);
+    /**
+     * Create a new OAuth application. Client secret is returned only once.
+     */
+    createApp(data: CreateOAuthAppInput): Promise<OAuthAppWithSecret>;
+    /**
+     * Get OAuth application by client ID
+     */
+    getApp(clientId: string): Promise<OAuthApp>;
+    /**
+     * List OAuth applications for an organization
+     */
+    listApps(organizationId: string): Promise<OAuthApp[]>;
+    /**
+     * Update OAuth application
+     */
+    updateApp(clientId: string, data: UpdateOAuthAppInput): Promise<OAuthApp>;
+    /**
+     * Delete OAuth application. All associated tokens will be revoked.
+     */
+    deleteApp(clientId: string): Promise<void>;
+    /**
+     * List active tokens for an OAuth application
+     */
+    listTokens(clientId: string): Promise<OAuthToken[]>;
+    /**
+     * Revoke an OAuth token (requires write:oauth-apps scope)
+     */
+    revokeToken(tokenId: string): Promise<void>;
+    /**
+     * Generate an access token using client credentials flow
+     */
+    generateToken(data: GenerateTokenInput): Promise<TokenResponse>;
+    /**
+     * Exchange an authorization code for access and refresh tokens
+     */
+    exchangeCode(data: ExchangeCodeInput): Promise<TokenResponse>;
+    /**
+     * Refresh an access token using a refresh token
+     */
+    refreshToken(data: RefreshTokenInput): Promise<TokenResponse>;
+}
+
+declare class OrganizationsResource {
+    private http;
+    constructor(http: KyInstance);
+    /**
+     * Create a new organization
+     */
+    create(data: CreateOrganizationInput): Promise<Organization>;
+    /**
+     * Get organization by ID
+     */
+    get(id: string): Promise<OrganizationDetails>;
+    /**
+     * Update organization (owner only)
+     */
+    update(id: string, data: UpdateOrganizationInput): Promise<Organization>;
+    /**
+     * Update organization legal/fiscal data (owner only)
+     */
+    updateLegalData(id: string, data: UpdateLegalDataInput): Promise<OrganizationDetails>;
+    /**
+     * Delete organization (owner only)
+     */
+    delete(id: string): Promise<void>;
+    /**
+     * Get organization members
+     */
+    members(id: string): Promise<OrganizationMember[]>;
+    /**
+     * Invite a member (owner/admin only)
+     */
+    invite(id: string, data: InviteMemberInput): Promise<OrganizationInvite>;
+    /**
+     * Remove a member (owner/admin only)
+     */
+    removeMember(id: string, memberId: string): Promise<void>;
+    /**
+     * Update member role (owner/admin only)
+     */
+    updateMemberRole(id: string, memberId: string, data: UpdateMemberRoleInput): Promise<OrganizationMember>;
+    /**
+     * Get pending invitations
+     */
+    invites(id: string): Promise<OrganizationInvite[]>;
+    /**
+     * Cancel a pending invitation (owner/admin only)
+     */
+    cancelInvite(id: string, inviteId: string): Promise<void>;
+}
+
+declare class ProductsResource {
+    private http;
+    constructor(http: KyInstance);
+    /**
+     * List products for an organization, with optional filters
+     */
+    list(organizationId: string, filters?: ListProductsFilters): Promise<Product[]>;
+    /**
+     * Get a product by ID
+     */
+    get(organizationId: string, productId: string): Promise<Product>;
+    /**
+     * Create a new product or service
+     */
+    create(organizationId: string, data: CreateProductInput): Promise<Product>;
+    /**
+     * Update a product
+     */
+    update(organizationId: string, productId: string, data: UpdateProductInput): Promise<Product>;
+    /**
+     * Delete a product
+     */
+    delete(organizationId: string, productId: string): Promise<void>;
+}
+
+declare class UsersResource {
+    private http;
+    constructor(http: KyInstance);
+    /**
+     * Get the currently authenticated user
+     */
+    me(): Promise<TimbrixUser>;
+    /**
+     * Get user by ID (requires read:user scope)
+     */
+    getById(id: string): Promise<TimbrixUser>;
+    /**
+     * Get organizations for a user (requires read:organization scope)
+     */
+    getOrganizations(id: string): Promise<OrganizationDetails[]>;
+    /**
+     * Get user by email (requires read:user scope)
+     */
+    getByEmail(email: string): Promise<TimbrixUser>;
+}
+
+declare class WebhooksResource {
+    private http;
+    constructor(http: KyInstance);
+    /**
+     * List all webhooks for an organization
+     */
+    list(organizationId: string): Promise<Webhook[]>;
+    /**
+     * Get webhook by ID
+     */
+    get(organizationId: string, webhookId: string): Promise<Webhook>;
+    /**
+     * Create a new webhook
+     */
+    create(organizationId: string, data: CreateWebhookInput): Promise<Webhook>;
+    /**
+     * Update webhook
+     */
+    update(organizationId: string, webhookId: string, data: UpdateWebhookInput): Promise<Webhook>;
+    /**
+     * Delete webhook
+     */
+    delete(organizationId: string, webhookId: string): Promise<void>;
+    /**
+     * Get webhook delivery history
+     */
+    deliveries(organizationId: string, webhookId: string): Promise<WebhookDelivery[]>;
+    /**
+     * Send test webhook
+     */
+    test(organizationId: string, webhookId: string): Promise<{
+        message: string;
+    }>;
+}
+
+declare class Timbrix {
+    private http;
+    private authStrategy?;
+    readonly auth: AuthResource;
+    readonly organizations: OrganizationsResource;
+    readonly webhooks: WebhooksResource;
+    readonly apiKeys: ApiKeysResource;
+    readonly users: UsersResource;
+    readonly customers: CustomersResource;
+    readonly oauth: OAuthResource;
+    readonly products: ProductsResource;
+    constructor(config?: TimbrixConfig);
+    /**
+     * Update authentication strategy (useful for CLI when token changes)
+     */
+    setAuth(bearerToken?: string, apiKey?: string): void;
+    /**
+     * Make a custom request
+     */
+    request<T>(url: string, options?: Options): Promise<T>;
+}
+
+interface AuthStrategy {
+    getHeaders(): Record<string, string>;
+    applyAuth(options: Options): Options;
+}
+declare class BearerAuth implements AuthStrategy {
+    private token;
+    constructor(token: string);
+    getHeaders(): Record<string, string>;
+    applyAuth(options: Options): Options;
+}
+declare class ApiKeyAuth implements AuthStrategy {
+    private apiKey;
+    constructor(apiKey: string);
+    getHeaders(): Record<string, string>;
+    applyAuth(options: Options): Options;
+}
+
+export { type ApiKey, ApiKeyAuth, type ApiKeyScope, type ApiKeyStats, type ApiKeyValidateResponse, ApiKeysResource, type AuthMode, AuthResource, type AuthStrategy, BearerAuth, type CreateApiKeyInput, type CreateApiKeyResponse, type CreateCustomerInput, type CreateOAuthAppInput, type CreateOrganizationInput, type CreateProductInput, type CreateWebhookInput, type Customer, type CustomerAddress, CustomersResource, type ExchangeCodeInput, type GenerateTokenInput, type InviteMemberInput, type LegalAddress, type ListProductsFilters, type LoginInput, type LoginResponse, type OAuthApp, type OAuthAppWithSecret, OAuthResource, type OAuthScope, type OAuthToken, type Organization, type OrganizationDetails, type OrganizationInvite, type OrganizationMember, type OrganizationRole, OrganizationsResource, type Product, type ProductTax, ProductsResource, type RefreshTokenInput, Timbrix, type TimbrixConfig, type TimbrixError, type TimbrixUser, type TokenResponse, type UpdateApiKeyInput, type UpdateCustomerInput, type UpdateLegalDataInput, type UpdateMemberRoleInput, type UpdateOAuthAppInput, type UpdateOrganizationInput, type UpdateProductInput, type UpdateWebhookInput, UsersResource, type ValidateCertificateResponse, type Webhook, type WebhookDelivery, type WebhookEvent, WebhooksResource };