@scell/sdk 1.0.0

package/src/resources/webhooks.ts

@@ -0,0 +1,258 @@
+/**
+ * Webhooks Resource
+ *
+ * @packageDocumentation
+ */
+
+import type { HttpClient, RequestOptions } from '../client.js';
+import type {
+  MessageResponse,
+  MessageWithDataResponse,
+  PaginatedResponse,
+} from '../types/common.js';
+import type {
+  CreateWebhookInput,
+  UpdateWebhookInput,
+  Webhook,
+  WebhookListOptions,
+  WebhookLog,
+  WebhookTestResponse,
+  WebhookWithSecret,
+} from '../types/webhooks.js';
+
+/**
+ * Webhooks API resource
+ *
+ * @example
+ * ```typescript
+ * // Create a webhook
+ * const webhook = await client.webhooks.create({
+ *   url: 'https://myapp.com/webhooks/scell',
+ *   events: ['invoice.validated', 'signature.completed'],
+ *   environment: 'production'
+ * });
+ *
+ * // Store the secret securely!
+ * console.log('Webhook secret:', webhook.secret);
+ *
+ * // Test the webhook
+ * const test = await client.webhooks.test(webhook.id);
+ * console.log('Test success:', test.success);
+ * ```
+ */
+export class WebhooksResource {
+  constructor(private readonly http: HttpClient) {}
+
+  /**
+   * List all webhooks
+   *
+   * @param options - Filter options
+   * @param requestOptions - Request options
+   * @returns List of webhooks
+   *
+   * @example
+   * ```typescript
+   * const { data: webhooks } = await client.webhooks.list();
+   * webhooks.forEach(wh => {
+   *   console.log(`${wh.url}: ${wh.is_active ? 'active' : 'inactive'}`);
+   * });
+   * ```
+   */
+  async list(
+    options: WebhookListOptions = {},
+    requestOptions?: RequestOptions
+  ): Promise<{ data: Webhook[] }> {
+    return this.http.get<{ data: Webhook[] }>(
+      '/webhooks',
+      options as Record<string, string | number | boolean | undefined>,
+      requestOptions
+    );
+  }
+
+  /**
+   * Create a new webhook
+   *
+   * Important: The secret is only returned once during creation.
+   * Store it securely - you'll need it to verify webhook signatures.
+   *
+   * @param input - Webhook configuration
+   * @param requestOptions - Request options
+   * @returns Created webhook with secret
+   *
+   * @example
+   * ```typescript
+   * const { data: webhook } = await client.webhooks.create({
+   *   url: 'https://myapp.com/webhooks/scell',
+   *   events: [
+   *     'invoice.created',
+   *     'invoice.validated',
+   *     'signature.completed',
+   *     'balance.low'
+   *   ],
+   *   environment: 'production',
+   *   headers: {
+   *     'X-Custom-Auth': 'my-secret-token'
+   *   },
+   *   retry_count: 5,
+   *   timeout_seconds: 30
+   * });
+   *
+   * // IMPORTANT: Store this secret securely!
+   * await saveWebhookSecret(webhook.id, webhook.secret);
+   * ```
+   */
+  async create(
+    input: CreateWebhookInput,
+    requestOptions?: RequestOptions
+  ): Promise<MessageWithDataResponse<WebhookWithSecret>> {
+    return this.http.post<MessageWithDataResponse<WebhookWithSecret>>(
+      '/webhooks',
+      input,
+      requestOptions
+    );
+  }
+
+  /**
+   * Update a webhook
+   *
+   * @param id - Webhook UUID
+   * @param input - Fields to update
+   * @param requestOptions - Request options
+   * @returns Updated webhook
+   *
+   * @example
+   * ```typescript
+   * // Disable a webhook temporarily
+   * await client.webhooks.update('webhook-uuid', {
+   *   is_active: false
+   * });
+   *
+   * // Update events
+   * await client.webhooks.update('webhook-uuid', {
+   *   events: ['invoice.validated', 'signature.completed']
+   * });
+   * ```
+   */
+  async update(
+    id: string,
+    input: UpdateWebhookInput,
+    requestOptions?: RequestOptions
+  ): Promise<MessageWithDataResponse<Webhook>> {
+    return this.http.put<MessageWithDataResponse<Webhook>>(
+      `/webhooks/${id}`,
+      input,
+      requestOptions
+    );
+  }
+
+  /**
+   * Delete a webhook
+   *
+   * @param id - Webhook UUID
+   * @param requestOptions - Request options
+   * @returns Deletion confirmation
+   *
+   * @example
+   * ```typescript
+   * await client.webhooks.delete('webhook-uuid');
+   * ```
+   */
+  async delete(
+    id: string,
+    requestOptions?: RequestOptions
+  ): Promise<MessageResponse> {
+    return this.http.delete<MessageResponse>(`/webhooks/${id}`, requestOptions);
+  }
+
+  /**
+   * Regenerate webhook secret
+   *
+   * Use this if your secret has been compromised.
+   * The old secret will immediately stop working.
+   *
+   * @param id - Webhook UUID
+   * @param requestOptions - Request options
+   * @returns Webhook with new secret
+   *
+   * @example
+   * ```typescript
+   * const { data: webhook } = await client.webhooks.regenerateSecret(
+   *   'webhook-uuid'
+   * );
+   *
+   * // Update your stored secret
+   * await updateWebhookSecret(webhook.id, webhook.secret);
+   * ```
+   */
+  async regenerateSecret(
+    id: string,
+    requestOptions?: RequestOptions
+  ): Promise<MessageWithDataResponse<WebhookWithSecret>> {
+    return this.http.post<MessageWithDataResponse<WebhookWithSecret>>(
+      `/webhooks/${id}/regenerate-secret`,
+      undefined,
+      requestOptions
+    );
+  }
+
+  /**
+   * Test webhook by sending a test event
+   *
+   * @param id - Webhook UUID
+   * @param requestOptions - Request options
+   * @returns Test result
+   *
+   * @example
+   * ```typescript
+   * const result = await client.webhooks.test('webhook-uuid');
+   *
+   * if (result.success) {
+   *   console.log(`Success! Response time: ${result.response_time_ms}ms`);
+   * } else {
+   *   console.log(`Failed: ${result.error}`);
+   * }
+   * ```
+   */
+  async test(
+    id: string,
+    requestOptions?: RequestOptions
+  ): Promise<WebhookTestResponse> {
+    return this.http.post<WebhookTestResponse>(
+      `/webhooks/${id}/test`,
+      undefined,
+      requestOptions
+    );
+  }
+
+  /**
+   * Get webhook delivery logs
+   *
+   * @param id - Webhook UUID
+   * @param options - Pagination options
+   * @param requestOptions - Request options
+   * @returns Paginated list of logs
+   *
+   * @example
+   * ```typescript
+   * const { data: logs } = await client.webhooks.logs('webhook-uuid', {
+   *   per_page: 50
+   * });
+   *
+   * logs.forEach(log => {
+   *   const status = log.success ? 'OK' : 'FAILED';
+   *   console.log(`${log.event} - ${status} (${log.response_time_ms}ms)`);
+   * });
+   * ```
+   */
+  async logs(
+    id: string,
+    options: { per_page?: number } = {},
+    requestOptions?: RequestOptions
+  ): Promise<PaginatedResponse<WebhookLog>> {
+    return this.http.get<PaginatedResponse<WebhookLog>>(
+      `/webhooks/${id}/logs`,
+      options,
+      requestOptions
+    );
+  }
+}

package/src/types/api-keys.ts

@@ -0,0 +1,35 @@
+import type { DateTimeString, Environment, UUID } from './common.js';
+
+/**
+ * API Key entity
+ */
+export interface ApiKey {
+  id: UUID;
+  name: string;
+  company_id: UUID;
+  key_prefix: string;
+  environment: Environment;
+  permissions: string[];
+  rate_limit: number;
+  last_used_at: DateTimeString | null;
+  expires_at: DateTimeString | null;
+  created_at: DateTimeString;
+}
+
+/**
+ * API Key with full key (returned on creation only)
+ */
+export interface ApiKeyWithSecret extends ApiKey {
+  key: string;
+}
+
+/**
+ * API Key creation input
+ */
+export interface CreateApiKeyInput {
+  name: string;
+  company_id: UUID;
+  environment: Environment;
+  permissions?: string[] | undefined;
+  expires_at?: DateTimeString | undefined;
+}

package/src/types/auth.ts

@@ -0,0 +1,58 @@
+import type { DateTimeString, UUID } from './common.js';
+
+/**
+ * User entity
+ */
+export interface User {
+  id: UUID;
+  name: string;
+  email: string;
+  email_verified_at: DateTimeString | null;
+  is_admin: boolean;
+  created_at: DateTimeString;
+  updated_at: DateTimeString;
+}
+
+/**
+ * Login credentials
+ */
+export interface LoginCredentials {
+  email: string;
+  password: string;
+}
+
+/**
+ * Registration input
+ */
+export interface RegisterInput {
+  name: string;
+  email: string;
+  password: string;
+  password_confirmation: string;
+}
+
+/**
+ * Auth response with token
+ */
+export interface AuthResponse {
+  message: string;
+  user: User;
+  token: string;
+}
+
+/**
+ * Password reset request input
+ */
+export interface ForgotPasswordInput {
+  email: string;
+}
+
+/**
+ * Password reset input
+ */
+export interface ResetPasswordInput {
+  email: string;
+  token: string;
+  password: string;
+  password_confirmation: string;
+}

package/src/types/balance.ts

@@ -0,0 +1,87 @@
+import type {
+  CurrencyCode,
+  DateRangeOptions,
+  DateTimeString,
+  PaginationOptions,
+  UUID,
+} from './common.js';
+
+/**
+ * Transaction type
+ */
+export type TransactionType = 'credit' | 'debit';
+
+/**
+ * Transaction service
+ */
+export type TransactionService = 'invoice' | 'signature' | 'manual' | 'admin';
+
+/**
+ * Balance entity
+ */
+export interface Balance {
+  amount: number;
+  currency: CurrencyCode;
+  auto_reload_enabled: boolean;
+  auto_reload_threshold: number | null;
+  auto_reload_amount: number | null;
+  low_balance_alert_threshold: number;
+  critical_balance_alert_threshold: number;
+}
+
+/**
+ * Transaction entity
+ */
+export interface Transaction {
+  id: UUID;
+  type: TransactionType;
+  service: TransactionService;
+  amount: number;
+  balance_before: number;
+  balance_after: number;
+  description: string;
+  reference_type: string | null;
+  reference_id: UUID | null;
+  created_at: DateTimeString;
+}
+
+/**
+ * Balance reload input
+ */
+export interface ReloadBalanceInput {
+  /** Amount to reload (10-10000 EUR) */
+  amount: number;
+}
+
+/**
+ * Balance reload response
+ */
+export interface ReloadBalanceResponse {
+  message: string;
+  transaction: {
+    id: UUID;
+    amount: number;
+    balance_after: number;
+  };
+}
+
+/**
+ * Balance settings update input
+ */
+export interface UpdateBalanceSettingsInput {
+  auto_reload_enabled?: boolean | undefined;
+  auto_reload_threshold?: number | undefined;
+  auto_reload_amount?: number | undefined;
+  low_balance_alert_threshold?: number | undefined;
+  critical_balance_alert_threshold?: number | undefined;
+}
+
+/**
+ * Transaction list filter options
+ */
+export interface TransactionListOptions
+  extends PaginationOptions,
+    DateRangeOptions {
+  type?: TransactionType | undefined;
+  service?: TransactionService | undefined;
+}

package/src/types/common.ts

@@ -0,0 +1,114 @@
+/**
+ * Common types used across the SDK
+ */
+
+/**
+ * Environment mode for API operations
+ */
+export type Environment = 'sandbox' | 'production';
+
+/**
+ * ISO 8601 date string (YYYY-MM-DD)
+ */
+export type DateString = string;
+
+/**
+ * ISO 8601 datetime string
+ */
+export type DateTimeString = string;
+
+/**
+ * UUID string
+ */
+export type UUID = string;
+
+/**
+ * French SIRET number (14 digits)
+ */
+export type Siret = string;
+
+/**
+ * French SIREN number (9 digits)
+ */
+export type Siren = string;
+
+/**
+ * Currency code (ISO 4217)
+ */
+export type CurrencyCode = string;
+
+/**
+ * Address structure
+ */
+export interface Address {
+  line1: string;
+  line2?: string | undefined;
+  postal_code: string;
+  city: string;
+  country?: string | undefined;
+}
+
+/**
+ * Pagination metadata
+ */
+export interface PaginationMeta {
+  current_page: number;
+  last_page: number;
+  per_page: number;
+  total: number;
+}
+
+/**
+ * Paginated response wrapper
+ */
+export interface PaginatedResponse<T> {
+  data: T[];
+  meta: PaginationMeta;
+}
+
+/**
+ * Single item response wrapper
+ */
+export interface SingleResponse<T> {
+  data: T;
+}
+
+/**
+ * Message response
+ */
+export interface MessageResponse {
+  message: string;
+}
+
+/**
+ * Message with data response
+ */
+export interface MessageWithDataResponse<T> {
+  message: string;
+  data: T;
+}
+
+/**
+ * Pagination options for list requests
+ */
+export interface PaginationOptions {
+  page?: number | undefined;
+  per_page?: number | undefined;
+}
+
+/**
+ * Date range filter options
+ */
+export interface DateRangeOptions {
+  from?: DateString | undefined;
+  to?: DateString | undefined;
+}
+
+/**
+ * API error response structure
+ */
+export interface ApiErrorResponse {
+  message: string;
+  errors?: Record<string, string[]> | undefined;
+  code?: string | undefined;
+}

package/src/types/companies.ts

@@ -0,0 +1,86 @@
+import type { DateTimeString, Siren, Siret, UUID } from './common.js';
+
+/**
+ * Company KYC status
+ */
+export type CompanyStatus = 'pending_kyc' | 'active' | 'suspended';
+
+/**
+ * Company entity
+ */
+export interface Company {
+  id: UUID;
+  name: string;
+  siret: Siret;
+  siren: Siren | null;
+  vat_number: string | null;
+  legal_form: string | null;
+  address_line1: string;
+  address_line2: string | null;
+  postal_code: string;
+  city: string;
+  country: string;
+  phone: string | null;
+  email: string | null;
+  website: string | null;
+  logo_url: string | null;
+  status: CompanyStatus;
+  kyc_completed_at: DateTimeString | null;
+  created_at: DateTimeString;
+  updated_at: DateTimeString;
+}
+
+/**
+ * Company creation input
+ */
+export interface CreateCompanyInput {
+  name: string;
+  siret: Siret;
+  vat_number?: string | undefined;
+  legal_form?: string | undefined;
+  address_line1: string;
+  address_line2?: string | undefined;
+  postal_code: string;
+  city: string;
+  country?: string | undefined;
+  phone?: string | undefined;
+  email?: string | undefined;
+  website?: string | undefined;
+}
+
+/**
+ * Company update input
+ */
+export interface UpdateCompanyInput {
+  name?: string | undefined;
+  siret?: Siret | undefined;
+  vat_number?: string | undefined;
+  legal_form?: string | undefined;
+  address_line1?: string | undefined;
+  address_line2?: string | undefined;
+  postal_code?: string | undefined;
+  city?: string | undefined;
+  country?: string | undefined;
+  phone?: string | undefined;
+  email?: string | undefined;
+  website?: string | undefined;
+}
+
+/**
+ * KYC initiation response
+ */
+export interface KycInitiateResponse {
+  message: string;
+  kyc_reference: string;
+  redirect_url: string;
+}
+
+/**
+ * KYC status response
+ */
+export interface KycStatusResponse {
+  status: CompanyStatus;
+  kyc_reference: string | null;
+  kyc_completed_at: DateTimeString | null;
+  message: string;
+}