@scell/sdk 1.0.0

package/src/errors.ts

@@ -0,0 +1,256 @@
+/**
+ * Scell SDK Error Classes
+ *
+ * @packageDocumentation
+ */
+
+import type { ApiErrorResponse } from './types/common.js';
+
+/**
+ * Base error class for all Scell API errors
+ */
+export class ScellError extends Error {
+  /** HTTP status code */
+  public readonly status: number;
+  /** Error code from API */
+  public readonly code: string | undefined;
+  /** Original response body */
+  public readonly body: unknown;
+
+  constructor(
+    message: string,
+    status: number,
+    code?: string,
+    body?: unknown
+  ) {
+    super(message);
+    this.name = 'ScellError';
+    this.status = status;
+    this.code = code;
+    this.body = body;
+
+    // Maintains proper stack trace in V8 environments
+    if (Error.captureStackTrace) {
+      Error.captureStackTrace(this, this.constructor);
+    }
+  }
+}
+
+/**
+ * Error thrown when authentication fails (401)
+ *
+ * @example
+ * ```typescript
+ * try {
+ *   await client.invoices.list();
+ * } catch (error) {
+ *   if (error instanceof ScellAuthenticationError) {
+ *     console.log('Invalid or expired token');
+ *   }
+ * }
+ * ```
+ */
+export class ScellAuthenticationError extends ScellError {
+  constructor(message = 'Authentication failed', body?: unknown) {
+    super(message, 401, 'AUTHENTICATION_ERROR', body);
+    this.name = 'ScellAuthenticationError';
+  }
+}
+
+/**
+ * Error thrown when authorization fails (403)
+ *
+ * @example
+ * ```typescript
+ * try {
+ *   await client.admin.users();
+ * } catch (error) {
+ *   if (error instanceof ScellAuthorizationError) {
+ *     console.log('Insufficient permissions');
+ *   }
+ * }
+ * ```
+ */
+export class ScellAuthorizationError extends ScellError {
+  constructor(message = 'Access denied', body?: unknown) {
+    super(message, 403, 'AUTHORIZATION_ERROR', body);
+    this.name = 'ScellAuthorizationError';
+  }
+}
+
+/**
+ * Error thrown when validation fails (422)
+ *
+ * @example
+ * ```typescript
+ * try {
+ *   await client.invoices.create(invalidData);
+ * } catch (error) {
+ *   if (error instanceof ScellValidationError) {
+ *     console.log('Validation errors:', error.errors);
+ *   }
+ * }
+ * ```
+ */
+export class ScellValidationError extends ScellError {
+  /** Field-level validation errors */
+  public readonly errors: Record<string, string[]>;
+
+  constructor(
+    message: string,
+    errors: Record<string, string[]> = {},
+    body?: unknown
+  ) {
+    super(message, 422, 'VALIDATION_ERROR', body);
+    this.name = 'ScellValidationError';
+    this.errors = errors;
+  }
+
+  /**
+   * Get all error messages as a flat array
+   */
+  getAllMessages(): string[] {
+    return Object.values(this.errors).flat();
+  }
+
+  /**
+   * Get error messages for a specific field
+   */
+  getFieldErrors(field: string): string[] {
+    return this.errors[field] ?? [];
+  }
+
+  /**
+   * Check if a specific field has errors
+   */
+  hasFieldError(field: string): boolean {
+    const fieldErrors = this.errors[field];
+    return fieldErrors !== undefined && fieldErrors.length > 0;
+  }
+}
+
+/**
+ * Error thrown when rate limit is exceeded (429)
+ *
+ * @example
+ * ```typescript
+ * try {
+ *   await client.invoices.create(data);
+ * } catch (error) {
+ *   if (error instanceof ScellRateLimitError) {
+ *     console.log(`Retry after ${error.retryAfter} seconds`);
+ *   }
+ * }
+ * ```
+ */
+export class ScellRateLimitError extends ScellError {
+  /** Seconds to wait before retrying */
+  public readonly retryAfter: number | undefined;
+
+  constructor(
+    message = 'Rate limit exceeded',
+    retryAfter?: number,
+    body?: unknown
+  ) {
+    super(message, 429, 'RATE_LIMIT_EXCEEDED', body);
+    this.name = 'ScellRateLimitError';
+    this.retryAfter = retryAfter;
+  }
+}
+
+/**
+ * Error thrown when a resource is not found (404)
+ */
+export class ScellNotFoundError extends ScellError {
+  constructor(message = 'Resource not found', body?: unknown) {
+    super(message, 404, 'NOT_FOUND', body);
+    this.name = 'ScellNotFoundError';
+  }
+}
+
+/**
+ * Error thrown when the API returns a server error (5xx)
+ */
+export class ScellServerError extends ScellError {
+  constructor(
+    message = 'Internal server error',
+    status = 500,
+    body?: unknown
+  ) {
+    super(message, status, 'SERVER_ERROR', body);
+    this.name = 'ScellServerError';
+  }
+}
+
+/**
+ * Error thrown when insufficient balance for an operation
+ */
+export class ScellInsufficientBalanceError extends ScellError {
+  constructor(message = 'Insufficient balance', body?: unknown) {
+    super(message, 402, 'INSUFFICIENT_BALANCE', body);
+    this.name = 'ScellInsufficientBalanceError';
+  }
+}
+
+/**
+ * Error thrown for network-related issues
+ */
+export class ScellNetworkError extends ScellError {
+  public readonly originalError: Error;
+
+  constructor(message: string, originalError: Error) {
+    super(message, 0, 'NETWORK_ERROR');
+    this.name = 'ScellNetworkError';
+    this.originalError = originalError;
+  }
+}
+
+/**
+ * Error thrown when request times out
+ */
+export class ScellTimeoutError extends ScellError {
+  constructor(message = 'Request timed out') {
+    super(message, 0, 'TIMEOUT');
+    this.name = 'ScellTimeoutError';
+  }
+}
+
+/**
+ * Parse API error response and throw appropriate error
+ */
+export function parseApiError(
+  status: number,
+  body: unknown,
+  headers?: Headers
+): never {
+  const errorBody = body as ApiErrorResponse | undefined;
+  const message = errorBody?.message ?? 'Unknown error';
+  const errors = errorBody?.errors ?? {};
+  const code = errorBody?.code;
+
+  switch (status) {
+    case 401:
+      throw new ScellAuthenticationError(message, body);
+    case 402:
+      throw new ScellInsufficientBalanceError(message, body);
+    case 403:
+      throw new ScellAuthorizationError(message, body);
+    case 404:
+      throw new ScellNotFoundError(message, body);
+    case 422:
+      throw new ScellValidationError(message, errors, body);
+    case 429: {
+      const retryAfter = headers?.get('Retry-After');
+      throw new ScellRateLimitError(
+        message,
+        retryAfter ? parseInt(retryAfter, 10) : undefined,
+        body
+      );
+    }
+    default:
+      if (status >= 500) {
+        throw new ScellServerError(message, status, body);
+      }
+      throw new ScellError(message, status, code, body);
+  }
+}

package/src/index.ts

@@ -0,0 +1,195 @@
+/**
+ * Scell.io Official TypeScript SDK
+ *
+ * @packageDocumentation
+ *
+ * @example
+ * ```typescript
+ * import { ScellClient, ScellApiClient, ScellAuth, ScellWebhooks } from '@scell/sdk';
+ *
+ * // Dashboard client (Bearer token)
+ * const auth = await ScellAuth.login({ email, password });
+ * const client = new ScellClient(auth.token);
+ *
+ * // API client (X-API-Key)
+ * const apiClient = new ScellApiClient('your-api-key');
+ *
+ * // Create invoice
+ * const invoice = await apiClient.invoices.create({...});
+ *
+ * // Verify webhook
+ * const isValid = await ScellWebhooks.verifySignature(payload, signature, secret);
+ * ```
+ */
+
+// Client
+import { HttpClient, type ClientConfig } from './client.js';
+
+// Resources
+import { ApiKeysResource } from './resources/api-keys.js';
+import { AuthResource, ScellAuth } from './resources/auth.js';
+import { BalanceResource } from './resources/balance.js';
+import { CompaniesResource } from './resources/companies.js';
+import { InvoicesResource } from './resources/invoices.js';
+import { SignaturesResource } from './resources/signatures.js';
+import { WebhooksResource } from './resources/webhooks.js';
+
+// Utilities
+import { ScellWebhooks } from './utils/webhook-verify.js';
+import { withRetry, createRetryWrapper } from './utils/retry.js';
+
+/**
+ * Scell Dashboard Client
+ *
+ * Use this client for dashboard/user operations with Bearer token authentication.
+ *
+ * @example
+ * ```typescript
+ * import { ScellClient, ScellAuth } from '@scell/sdk';
+ *
+ * // Login first
+ * const auth = await ScellAuth.login({
+ *   email: 'user@example.com',
+ *   password: 'password'
+ * });
+ *
+ * // Create client
+ * const client = new ScellClient(auth.token);
+ *
+ * // Use the client
+ * const companies = await client.companies.list();
+ * const balance = await client.balance.get();
+ * ```
+ */
+export class ScellClient {
+  private readonly http: HttpClient;
+
+  /** Authentication operations */
+  public readonly auth: AuthResource;
+  /** Company management */
+  public readonly companies: CompaniesResource;
+  /** API key management */
+  public readonly apiKeys: ApiKeysResource;
+  /** Balance and transactions */
+  public readonly balance: BalanceResource;
+  /** Webhook management */
+  public readonly webhooks: WebhooksResource;
+  /** Invoice listing (read-only via dashboard) */
+  public readonly invoices: InvoicesResource;
+  /** Signature listing (read-only via dashboard) */
+  public readonly signatures: SignaturesResource;
+
+  /**
+   * Create a new Scell Dashboard Client
+   *
+   * @param token - Bearer token from login
+   * @param config - Client configuration
+   *
+   * @example
+   * ```typescript
+   * const client = new ScellClient('your-bearer-token', {
+   *   baseUrl: 'https://api.scell.io/api/v1',
+   *   timeout: 30000,
+   *   retry: { maxRetries: 3 }
+   * });
+   * ```
+   */
+  constructor(token: string, config: ClientConfig = {}) {
+    this.http = new HttpClient('bearer', token, config);
+
+    this.auth = new AuthResource(this.http);
+    this.companies = new CompaniesResource(this.http);
+    this.apiKeys = new ApiKeysResource(this.http);
+    this.balance = new BalanceResource(this.http);
+    this.webhooks = new WebhooksResource(this.http);
+    this.invoices = new InvoicesResource(this.http);
+    this.signatures = new SignaturesResource(this.http);
+  }
+}
+
+/**
+ * Scell API Client
+ *
+ * Use this client for external API operations with X-API-Key authentication.
+ * This is the client you'll use for creating invoices and signatures.
+ *
+ * @example
+ * ```typescript
+ * import { ScellApiClient } from '@scell/sdk';
+ *
+ * const client = new ScellApiClient('your-api-key');
+ *
+ * // Create an invoice
+ * const invoice = await client.invoices.create({
+ *   invoice_number: 'FACT-2024-001',
+ *   direction: 'outgoing',
+ *   output_format: 'facturx',
+ *   // ...
+ * });
+ *
+ * // Create a signature request
+ * const signature = await client.signatures.create({
+ *   title: 'Contract',
+ *   document: btoa(pdfContent),
+ *   document_name: 'contract.pdf',
+ *   signers: [{...}]
+ * });
+ * ```
+ */
+export class ScellApiClient {
+  private readonly http: HttpClient;
+
+  /** Invoice operations (create, download, convert) */
+  public readonly invoices: InvoicesResource;
+  /** Signature operations (create, download, remind, cancel) */
+  public readonly signatures: SignaturesResource;
+
+  /**
+   * Create a new Scell API Client
+   *
+   * @param apiKey - Your API key (from dashboard)
+   * @param config - Client configuration
+   *
+   * @example
+   * ```typescript
+   * // Production client
+   * const client = new ScellApiClient('sk_live_xxx');
+   *
+   * // Sandbox client
+   * const sandboxClient = new ScellApiClient('sk_test_xxx', {
+   *   baseUrl: 'https://api.scell.io/api/v1/sandbox'
+   * });
+   * ```
+   */
+  constructor(apiKey: string, config: ClientConfig = {}) {
+    this.http = new HttpClient('api-key', apiKey, config);
+
+    this.invoices = new InvoicesResource(this.http);
+    this.signatures = new SignaturesResource(this.http);
+  }
+}
+
+// Re-export utilities
+export { ScellAuth, ScellWebhooks, withRetry, createRetryWrapper };
+
+// Re-export types
+export type { ClientConfig } from './client.js';
+export type { RetryOptions } from './utils/retry.js';
+export type { VerifySignatureOptions } from './utils/webhook-verify.js';
+
+// Re-export errors
+export {
+  ScellError,
+  ScellAuthenticationError,
+  ScellAuthorizationError,
+  ScellValidationError,
+  ScellRateLimitError,
+  ScellNotFoundError,
+  ScellServerError,
+  ScellInsufficientBalanceError,
+  ScellNetworkError,
+  ScellTimeoutError,
+} from './errors.js';
+
+// Re-export all types
+export * from './types/index.js';

package/src/resources/api-keys.ts

@@ -0,0 +1,141 @@
+/**
+ * API Keys Resource
+ *
+ * @packageDocumentation
+ */
+
+import type { HttpClient, RequestOptions } from '../client.js';
+import type {
+  MessageResponse,
+  MessageWithDataResponse,
+  SingleResponse,
+} from '../types/common.js';
+import type {
+  ApiKey,
+  ApiKeyWithSecret,
+  CreateApiKeyInput,
+} from '../types/api-keys.js';
+
+/**
+ * API Keys resource
+ *
+ * @example
+ * ```typescript
+ * // Create an API key for a company
+ * const apiKey = await client.apiKeys.create({
+ *   name: 'Production Key',
+ *   company_id: 'company-uuid',
+ *   environment: 'production'
+ * });
+ *
+ * // Store the key securely!
+ * console.log('API Key:', apiKey.key);
+ * ```
+ */
+export class ApiKeysResource {
+  constructor(private readonly http: HttpClient) {}
+
+  /**
+   * List all API keys
+   *
+   * @param requestOptions - Request options
+   * @returns List of API keys (without secrets)
+   *
+   * @example
+   * ```typescript
+   * const { data: keys } = await client.apiKeys.list();
+   * keys.forEach(key => {
+   *   console.log(`${key.name}: ${key.key_prefix}...`);
+   * });
+   * ```
+   */
+  async list(requestOptions?: RequestOptions): Promise<{ data: ApiKey[] }> {
+    return this.http.get<{ data: ApiKey[] }>(
+      '/api-keys',
+      undefined,
+      requestOptions
+    );
+  }
+
+  /**
+   * Get a specific API key
+   *
+   * @param id - API Key UUID
+   * @param requestOptions - Request options
+   * @returns API key details (without secret)
+   *
+   * @example
+   * ```typescript
+   * const { data: key } = await client.apiKeys.get('key-uuid');
+   * console.log(`Last used: ${key.last_used_at}`);
+   * ```
+   */
+  async get(
+    id: string,
+    requestOptions?: RequestOptions
+  ): Promise<SingleResponse<ApiKey>> {
+    return this.http.get<SingleResponse<ApiKey>>(
+      `/api-keys/${id}`,
+      undefined,
+      requestOptions
+    );
+  }
+
+  /**
+   * Create a new API key
+   *
+   * Important: The full key is only returned once during creation.
+   * Store it securely - you won't be able to retrieve it again.
+   *
+   * @param input - API key configuration
+   * @param requestOptions - Request options
+   * @returns Created API key with full key value
+   *
+   * @example
+   * ```typescript
+   * const { data: apiKey } = await client.apiKeys.create({
+   *   name: 'Production Integration',
+   *   company_id: 'company-uuid',
+   *   environment: 'production',
+   *   permissions: ['invoices:write', 'signatures:write']
+   * });
+   *
+   * // IMPORTANT: Store this key securely!
+   * // You won't be able to see it again.
+   * console.log('Save this key:', apiKey.key);
+   * ```
+   */
+  async create(
+    input: CreateApiKeyInput,
+    requestOptions?: RequestOptions
+  ): Promise<MessageWithDataResponse<ApiKeyWithSecret>> {
+    return this.http.post<MessageWithDataResponse<ApiKeyWithSecret>>(
+      '/api-keys',
+      input,
+      requestOptions
+    );
+  }
+
+  /**
+   * Delete an API key
+   *
+   * Warning: This will immediately revoke the key and all
+   * requests using it will fail.
+   *
+   * @param id - API Key UUID
+   * @param requestOptions - Request options
+   * @returns Deletion confirmation
+   *
+   * @example
+   * ```typescript
+   * await client.apiKeys.delete('key-uuid');
+   * console.log('API key revoked');
+   * ```
+   */
+  async delete(
+    id: string,
+    requestOptions?: RequestOptions
+  ): Promise<MessageResponse> {
+    return this.http.delete<MessageResponse>(`/api-keys/${id}`, requestOptions);
+  }
+}