@safercity/sdk-core 0.0.1

package/dist/index.d.cts

@@ -0,0 +1,243 @@
+/**
+ * Common types for SaferCity SDK
+ */
+interface SaferCityConfig {
+    /**
+     * Base URL for the SaferCity API
+     * @example "https://api.safercity.com"
+     */
+    baseUrl: string;
+    /**
+     * Authentication token (JWT)
+     */
+    token?: string;
+    /**
+     * Tenant ID for multi-tenant operations
+     */
+    tenantId?: string;
+    /**
+     * Custom fetch implementation (useful for React Native)
+     */
+    fetch?: typeof fetch;
+    /**
+     * Request timeout in milliseconds
+     * @default 30000
+     */
+    timeout?: number;
+    /**
+     * Custom headers to include in all requests
+     */
+    headers?: Record<string, string>;
+}
+interface RequestOptions {
+    /**
+     * Additional headers for this request
+     */
+    headers?: Record<string, string>;
+    /**
+     * Request timeout override
+     */
+    timeout?: number;
+    /**
+     * Abort signal for cancellation
+     */
+    signal?: AbortSignal;
+}
+interface ApiResponse<T> {
+    data: T;
+    status: number;
+    headers: Headers;
+}
+interface ApiError {
+    error: string;
+    message: string;
+    status: number;
+    details?: unknown;
+}
+declare class SaferCityApiError extends Error {
+    readonly error: string;
+    readonly status: number;
+    readonly details?: unknown | undefined;
+    constructor(error: string, message: string, status: number, details?: unknown | undefined);
+    static fromResponse(response: Response, body: unknown): SaferCityApiError;
+}
+/**
+ * Server-Sent Event structure
+ */
+interface ServerSentEvent {
+    id?: string;
+    event?: string;
+    data: string;
+    retry?: number;
+}
+/**
+ * Options for SSE connections
+ */
+interface EventSourceOptions {
+    headers?: Record<string, string>;
+    signal?: AbortSignal;
+    onOpen?: () => void;
+    onError?: (error: Error) => void;
+}
+
+/**
+ * Authentication utilities for SaferCity SDK
+ */
+interface AuthTokens {
+    accessToken: string;
+    refreshToken?: string;
+    expiresAt?: number;
+    tokenType: string;
+}
+interface TokenStorage {
+    get(): AuthTokens | null;
+    set(tokens: AuthTokens): void;
+    clear(): void;
+}
+/**
+ * In-memory token storage (default)
+ */
+declare class MemoryTokenStorage implements TokenStorage {
+    private tokens;
+    get(): AuthTokens | null;
+    set(tokens: AuthTokens): void;
+    clear(): void;
+}
+/**
+ * Check if a token is expired (with buffer)
+ */
+declare function isTokenExpired(expiresAt: number | undefined, bufferMs?: number): boolean;
+/**
+ * Create Authorization header value
+ */
+declare function createAuthHeader(token: string, type?: string): string;
+/**
+ * Parse JWT payload (without verification)
+ * Only use for client-side display, not security decisions
+ */
+declare function parseJwtPayload<T = Record<string, unknown>>(token: string): T | null;
+/**
+ * Extract expiration from JWT
+ */
+declare function getJwtExpiration(token: string): number | null;
+interface SaferCityJwtPayload {
+    sub?: string;
+    tenantId?: string;
+    environment?: string;
+    scopes?: string[];
+    iat?: number;
+    exp?: number;
+}
+
+/**
+ * Cross-platform SSE/Streaming support for SaferCity SDK
+ *
+ * Provides adapters for:
+ * - Web browsers (native EventSource)
+ * - React Native (fetch-based streaming via expo-fetch or polyfill)
+ * - Node.js (fetch-based streaming)
+ */
+
+/**
+ * Interface for stream adapters
+ */
+interface StreamAdapter {
+    /**
+     * Create an async iterable for SSE events
+     */
+    createEventSource(url: string, options?: EventSourceOptions): AsyncIterable<ServerSentEvent>;
+    /**
+     * Check if native SSE is supported
+     */
+    supportsNativeSSE(): boolean;
+}
+/**
+ * Parse SSE data from a text buffer
+ */
+declare function parseSSE(buffer: string): {
+    parsed: ServerSentEvent[];
+    remaining: string;
+};
+/**
+ * Web/Browser stream adapter using native EventSource
+ */
+declare class WebStreamAdapter implements StreamAdapter {
+    supportsNativeSSE(): boolean;
+    createEventSource(url: string, options?: EventSourceOptions): AsyncIterable<ServerSentEvent>;
+}
+/**
+ * Fetch-based stream adapter for React Native and Node.js
+ * Uses ReadableStream to parse SSE from fetch response
+ */
+declare class FetchStreamAdapter implements StreamAdapter {
+    private fetchFn;
+    constructor(fetchFn?: typeof fetch);
+    supportsNativeSSE(): boolean;
+    createEventSource(url: string, options?: EventSourceOptions): AsyncIterable<ServerSentEvent>;
+}
+/**
+ * Auto-detect and create the best stream adapter for the current environment
+ */
+declare function createStreamAdapter(fetchFn?: typeof fetch): StreamAdapter;
+
+/**
+ * Base HTTP client for SaferCity SDK
+ */
+
+interface BaseClientOptions extends SaferCityConfig {
+}
+/**
+ * Base HTTP client with common functionality
+ */
+declare class BaseClient {
+    protected config: Required<Pick<SaferCityConfig, 'baseUrl' | 'timeout'>> & SaferCityConfig;
+    protected fetchFn: typeof fetch;
+    constructor(options: BaseClientOptions);
+    /**
+     * Update authentication token
+     */
+    setToken(token: string | undefined): void;
+    /**
+     * Update tenant ID
+     */
+    setTenantId(tenantId: string | undefined): void;
+    /**
+     * Get current configuration (read-only)
+     */
+    getConfig(): Readonly<SaferCityConfig>;
+    /**
+     * Build full URL from path
+     */
+    protected buildUrl(path: string, query?: Record<string, string | number | boolean | undefined>): string;
+    /**
+     * Make HTTP request
+     */
+    protected request<T>(method: string, path: string, options?: RequestOptions & {
+        body?: unknown;
+        query?: Record<string, string | number | boolean | undefined>;
+    }): Promise<ApiResponse<T>>;
+    /**
+     * GET request
+     */
+    get<T>(path: string, options?: RequestOptions & {
+        query?: Record<string, string | number | boolean | undefined>;
+    }): Promise<ApiResponse<T>>;
+    /**
+     * POST request
+     */
+    post<T>(path: string, body?: unknown, options?: RequestOptions): Promise<ApiResponse<T>>;
+    /**
+     * PUT request
+     */
+    put<T>(path: string, body?: unknown, options?: RequestOptions): Promise<ApiResponse<T>>;
+    /**
+     * PATCH request
+     */
+    patch<T>(path: string, body?: unknown, options?: RequestOptions): Promise<ApiResponse<T>>;
+    /**
+     * DELETE request
+     */
+    delete<T>(path: string, options?: RequestOptions): Promise<ApiResponse<T>>;
+}
+
+export { type ApiError, type ApiResponse, type AuthTokens, BaseClient, type BaseClientOptions, type EventSourceOptions, FetchStreamAdapter, MemoryTokenStorage, type RequestOptions, SaferCityApiError, type SaferCityConfig, type SaferCityJwtPayload, type ServerSentEvent, type StreamAdapter, type TokenStorage, WebStreamAdapter, createAuthHeader, createStreamAdapter, getJwtExpiration, isTokenExpired, parseJwtPayload, parseSSE };

package/dist/index.d.ts

@@ -0,0 +1,243 @@
+/**
+ * Common types for SaferCity SDK
+ */
+interface SaferCityConfig {
+    /**
+     * Base URL for the SaferCity API
+     * @example "https://api.safercity.com"
+     */
+    baseUrl: string;
+    /**
+     * Authentication token (JWT)
+     */
+    token?: string;
+    /**
+     * Tenant ID for multi-tenant operations
+     */
+    tenantId?: string;
+    /**
+     * Custom fetch implementation (useful for React Native)
+     */
+    fetch?: typeof fetch;
+    /**
+     * Request timeout in milliseconds
+     * @default 30000
+     */
+    timeout?: number;
+    /**
+     * Custom headers to include in all requests
+     */
+    headers?: Record<string, string>;
+}
+interface RequestOptions {
+    /**
+     * Additional headers for this request
+     */
+    headers?: Record<string, string>;
+    /**
+     * Request timeout override
+     */
+    timeout?: number;
+    /**
+     * Abort signal for cancellation
+     */
+    signal?: AbortSignal;
+}
+interface ApiResponse<T> {
+    data: T;
+    status: number;
+    headers: Headers;
+}
+interface ApiError {
+    error: string;
+    message: string;
+    status: number;
+    details?: unknown;
+}
+declare class SaferCityApiError extends Error {
+    readonly error: string;
+    readonly status: number;
+    readonly details?: unknown | undefined;
+    constructor(error: string, message: string, status: number, details?: unknown | undefined);
+    static fromResponse(response: Response, body: unknown): SaferCityApiError;
+}
+/**
+ * Server-Sent Event structure
+ */
+interface ServerSentEvent {
+    id?: string;
+    event?: string;
+    data: string;
+    retry?: number;
+}
+/**
+ * Options for SSE connections
+ */
+interface EventSourceOptions {
+    headers?: Record<string, string>;
+    signal?: AbortSignal;
+    onOpen?: () => void;
+    onError?: (error: Error) => void;
+}
+
+/**
+ * Authentication utilities for SaferCity SDK
+ */
+interface AuthTokens {
+    accessToken: string;
+    refreshToken?: string;
+    expiresAt?: number;
+    tokenType: string;
+}
+interface TokenStorage {
+    get(): AuthTokens | null;
+    set(tokens: AuthTokens): void;
+    clear(): void;
+}
+/**
+ * In-memory token storage (default)
+ */
+declare class MemoryTokenStorage implements TokenStorage {
+    private tokens;
+    get(): AuthTokens | null;
+    set(tokens: AuthTokens): void;
+    clear(): void;
+}
+/**
+ * Check if a token is expired (with buffer)
+ */
+declare function isTokenExpired(expiresAt: number | undefined, bufferMs?: number): boolean;
+/**
+ * Create Authorization header value
+ */
+declare function createAuthHeader(token: string, type?: string): string;
+/**
+ * Parse JWT payload (without verification)
+ * Only use for client-side display, not security decisions
+ */
+declare function parseJwtPayload<T = Record<string, unknown>>(token: string): T | null;
+/**
+ * Extract expiration from JWT
+ */
+declare function getJwtExpiration(token: string): number | null;
+interface SaferCityJwtPayload {
+    sub?: string;
+    tenantId?: string;
+    environment?: string;
+    scopes?: string[];
+    iat?: number;
+    exp?: number;
+}
+
+/**
+ * Cross-platform SSE/Streaming support for SaferCity SDK
+ *
+ * Provides adapters for:
+ * - Web browsers (native EventSource)
+ * - React Native (fetch-based streaming via expo-fetch or polyfill)
+ * - Node.js (fetch-based streaming)
+ */
+
+/**
+ * Interface for stream adapters
+ */
+interface StreamAdapter {
+    /**
+     * Create an async iterable for SSE events
+     */
+    createEventSource(url: string, options?: EventSourceOptions): AsyncIterable<ServerSentEvent>;
+    /**
+     * Check if native SSE is supported
+     */
+    supportsNativeSSE(): boolean;
+}
+/**
+ * Parse SSE data from a text buffer
+ */
+declare function parseSSE(buffer: string): {
+    parsed: ServerSentEvent[];
+    remaining: string;
+};
+/**
+ * Web/Browser stream adapter using native EventSource
+ */
+declare class WebStreamAdapter implements StreamAdapter {
+    supportsNativeSSE(): boolean;
+    createEventSource(url: string, options?: EventSourceOptions): AsyncIterable<ServerSentEvent>;
+}
+/**
+ * Fetch-based stream adapter for React Native and Node.js
+ * Uses ReadableStream to parse SSE from fetch response
+ */
+declare class FetchStreamAdapter implements StreamAdapter {
+    private fetchFn;
+    constructor(fetchFn?: typeof fetch);
+    supportsNativeSSE(): boolean;
+    createEventSource(url: string, options?: EventSourceOptions): AsyncIterable<ServerSentEvent>;
+}
+/**
+ * Auto-detect and create the best stream adapter for the current environment
+ */
+declare function createStreamAdapter(fetchFn?: typeof fetch): StreamAdapter;
+
+/**
+ * Base HTTP client for SaferCity SDK
+ */
+
+interface BaseClientOptions extends SaferCityConfig {
+}
+/**
+ * Base HTTP client with common functionality
+ */
+declare class BaseClient {
+    protected config: Required<Pick<SaferCityConfig, 'baseUrl' | 'timeout'>> & SaferCityConfig;
+    protected fetchFn: typeof fetch;
+    constructor(options: BaseClientOptions);
+    /**
+     * Update authentication token
+     */
+    setToken(token: string | undefined): void;
+    /**
+     * Update tenant ID
+     */
+    setTenantId(tenantId: string | undefined): void;
+    /**
+     * Get current configuration (read-only)
+     */
+    getConfig(): Readonly<SaferCityConfig>;
+    /**
+     * Build full URL from path
+     */
+    protected buildUrl(path: string, query?: Record<string, string | number | boolean | undefined>): string;
+    /**
+     * Make HTTP request
+     */
+    protected request<T>(method: string, path: string, options?: RequestOptions & {
+        body?: unknown;
+        query?: Record<string, string | number | boolean | undefined>;
+    }): Promise<ApiResponse<T>>;
+    /**
+     * GET request
+     */
+    get<T>(path: string, options?: RequestOptions & {
+        query?: Record<string, string | number | boolean | undefined>;
+    }): Promise<ApiResponse<T>>;
+    /**
+     * POST request
+     */
+    post<T>(path: string, body?: unknown, options?: RequestOptions): Promise<ApiResponse<T>>;
+    /**
+     * PUT request
+     */
+    put<T>(path: string, body?: unknown, options?: RequestOptions): Promise<ApiResponse<T>>;
+    /**
+     * PATCH request
+     */
+    patch<T>(path: string, body?: unknown, options?: RequestOptions): Promise<ApiResponse<T>>;
+    /**
+     * DELETE request
+     */
+    delete<T>(path: string, options?: RequestOptions): Promise<ApiResponse<T>>;
+}
+
+export { type ApiError, type ApiResponse, type AuthTokens, BaseClient, type BaseClientOptions, type EventSourceOptions, FetchStreamAdapter, MemoryTokenStorage, type RequestOptions, SaferCityApiError, type SaferCityConfig, type SaferCityJwtPayload, type ServerSentEvent, type StreamAdapter, type TokenStorage, WebStreamAdapter, createAuthHeader, createStreamAdapter, getJwtExpiration, isTokenExpired, parseJwtPayload, parseSSE };