Integrations reference

import { integration } from 'deepspace'
import type { IntegrationResponse, RequestOptions } from 'deepspace'

const integration: {
  get<T>:    (endpoint: string, params?: Record<string, string | number | boolean | null | undefined>, options?: RequestOptions) => Promise<IntegrationResponse<T>>
  post<T>:   (endpoint: string, data?: unknown, options?: RequestOptions) => Promise<IntegrationResponse<T>>
  put<T>:    (endpoint: string, data?: unknown, options?: RequestOptions) => Promise<IntegrationResponse<T>>
  delete<T>: (endpoint: string, data?: unknown, options?: RequestOptions) => Promise<IntegrationResponse<T>>
}

type IntegrationResponse<T> =
  | { success: true; data: T }
  | { success: false; error: string; issues?: ValidationIssue[] }

type ValidationIssue = {
  path?: string[]
  message: string
  code?: string
}

type RequestOptions = {
  headers?: Record<string, string>
  timeoutMs?: number     // default 120000 (120s)
  signal?: AbortSignal   // cancel the request from the caller
}

const r = await integration.post('exa/search', body, {
  timeoutMs: 30_000,
  headers: { 'X-Custom': 'value' },
})

import { useAsyncResource, usePagedResource } from 'deepspace'

function useAsyncResource<T>(
  fetcher: (signal: AbortSignal) => Promise<T>,
  deps: readonly unknown[],
  options?: UseAsyncResourceOptions<T>,
): AsyncResourceState<T> & { reload: () => void }

type AsyncResourceState<T> = {
  status: 'idle' | 'loading' | 'ready' | 'error'
  data: T | null
  error: string | null
  isRefreshing: boolean   // a re-fetch is in flight while previous data stays visible
  isSlow: boolean         // the in-flight request has exceeded slowAfterMs
  retryCount: number
}

type UseAsyncResourceOptions<T> = {
  enabled?: boolean          // default true; false parks the hook at 'idle'
  initialData?: T | null
  keepPreviousData?: boolean // default true - previous data stays visible during re-fetch
  retry?: number             // automatic retries after failure; default 0
  retryDelayMs?: number      // default 2000
  slowAfterMs?: number       // default 10000; 0 disables the isSlow signal
}

function usePagedResource<T>(
  fetchPage: (args: { page: number; pageSize: number; signal: AbortSignal }) => Promise<{ items: T[]; hasMore?: boolean }>,
  deps: readonly unknown[],
  options?: UsePagedResourceOptions<T>,
): PagedResourceState<T> & {
  loadMore: () => void   // fetch the next page and append
  retry: () => void      // re-fire the failed page
  refresh: () => void    // restart from page 1
}

type PagedResourceState<T> = {
  status: 'idle' | 'loading' | 'ready' | 'error'
  items: T[]
  error: string | null
  warning: string | null   // set when an oversized page was clamped
  hasMore: boolean
  isLoadingInitial: boolean
  isLoadingMore: boolean
  isRefreshing: boolean
}

type UsePagedResourceOptions<T> = {
  enabled?: boolean
  initialItems?: T[]
  pageSize?: number          // default 20
  maxItemsPerPage?: number   // default pageSize; larger API pages are clamped with a warning
  keepPreviousData?: boolean // default true
  autoRetryOnError?: boolean // default false - failures wait for retry() with backoff otherwise off
  retryDelayMs?: number      // default 2000 (backoff base)
  maxRetryDelayMs?: number   // default 30000
}

import { PlatformProvider, usePlatform, useInbox, usePlatformWS } from 'deepspace'

<PlatformProvider>{/* tree */}</PlatformProvider>

function usePlatform(): {
  platformFetch: (path: string, init?: RequestInit) => Promise<Response>
  inbox: InboxEntry[]
  /** Activate the inbox WebSocket. Returns an unsubscribe function. */
  subscribeInbox: () => () => void
}

function useInbox(): InboxEntry[]

type InboxEntry = {
  conversationId: string
  scope: { type: string; participants?: string[]; appId?: string; contentRef?: string; ticketNumber?: string }
  displayName: string
  muted: boolean
  joinedAt: string
  lastMessageAt: string | null
  lastMessagePreview: string | null
  lastMessageAuthor: string | null
  unreadCount: number
}

function usePlatformWS<S extends { status: ConnectionStatus }>(
  options: PlatformWSOptions<S>,
): PlatformWSResult<S>

type PlatformWSOptions<S> = {
  /** DO path segment - e.g. 'orders' for /platform/ws/orders/{scopeId} */
  path: string
  /** Scope ID - e.g. 'app:app_01HZXYABCDEFGHJKMNPQRSTVWX'. Pass undefined to skip the connection. */
  scopeId: string | undefined
  initialState: S
  onMessage: (msg: Record<string, unknown>, prev: S) => S
}

type PlatformWSResult<S> = {
  state: S
  send: (msg: Record<string, unknown>) => void
}

const r = await fetch('/api/integrations/status', {
  headers: { Authorization: `Bearer ${await getAuthToken()}` },
})
const { google } = await r.json()
// {
//   connected: boolean,
//   gmailSend: boolean, gmailRead: boolean, gmailModify: boolean,
//   calendar: boolean, drive: boolean, contacts: boolean,
//   gmail: boolean,     // aggregate: gmailSend || gmailRead
//   email?: string      // connected account email, when known
// }

{
  success: true,
  data: {
    requiresOAuth: true,
    provider: 'google',
    scopes: string[],
    authUrl: string
  }
}