@decentrl/sdk

npm install @decentrl/sdk zod

import { defineDecentrlApp } from '@decentrl/sdk'

function defineDecentrlApp<TEvents, TState>(
  config: DecentrlAppConfig<TEvents, TState>,
): DecentrlApp<TEvents, TState>

interface DecentrlAppConfig<TEvents, TState> {
  events: TEvents       // Record<string, { schema: ZodType; tags: string[] }>
  state: TState          // Record<string, StateSliceDefinition>
}

type EventDefinitions = Record<string, {
  schema: z.ZodType     // validated at publish time
  tags: string[]         // template strings like "chat:${chatId}"
}>

interface StateSliceDefinition<TSlice, TEvents> {
  initial: TSlice
  reduce: {
    [K in keyof TEvents]?: (
      state: TSlice,
      data: z.infer<TEvents[K]['schema']>,
      meta: EventMeta,
    ) => TSlice
  }
}

const client = app.createClient({
  mediatorDid: 'did:web:mediator.decentrl.io',
  persist: { key: 'myapp' },         // optional localStorage persistence
  transport: customTransport,         // optional custom transport
})

interface DecentrlClientConfig {
  mediatorDid: string
  persist?: { key: string }
  transport?: DecentrlTransport
}

await client.publish<K extends keyof TEvents>(
  eventType: K,
  data: z.infer<TEvents[K]['schema']>,
  options?: { recipient?: string; ephemeral?: boolean },
): Promise<void>

client.getState(): InferState<TState>
client.subscribe(listener: (state) => void): () => void

client.query(options?: QueryOptions): Promise<PaginatedResult<EventEnvelope>>
client.queryAndProcess(options?: QueryOptions): Promise<{ processed: number; total: number }>
client.onEvent(listener: (envelope: EventEnvelope) => void): () => void

client.startSync(options?: SyncOptions): void
client.stopSync(): void
client.sync(): Promise<void>
client.getConnectionStatus(): ConnectionStatus
client.onConnectionStatusChange(listener: (status) => void): () => void

interface SyncOptions {
  intervalMs?: number
  fallbackIntervalMs?: number
  onError?: (error: unknown) => void
  websocket?: boolean
  autoRenew?: { enabled: boolean; threshold?: number }
}

type ConnectionStatus = 'disconnected' | 'connecting' | 'authenticating' | 'connected'

client.reset(): void

client.identity.getIdentity(): IdentityState | null
client.identity.requireIdentity(): IdentityState
client.identity.create({ alias, mediatorDid }): Promise<IdentityState>
client.identity.load(serialized: SerializedIdentity): IdentityState
client.identity.serialize(): SerializedIdentity
client.identity.reset(): void
client.identity.onChange(listener): () => void

client.contracts.request(recipientDid, expiresIn?): Promise<void>
client.contracts.getPending(): Promise<PendingContractRequest[]>
client.contracts.accept(pendingId, encryptedPayload, ephemeralPubKey): Promise<void>
client.contracts.refresh(): Promise<void>
client.contracts.getActiveContracts(): StoredSignedContract[]
client.contracts.getContractByDid(did): StoredSignedContract | undefined
client.contracts.processAutoRenewals(threshold?): Promise<void>
client.contracts.processContractCleanup(): Promise<void>
client.contracts.onChange(listener): () => void

interface EventMeta {
  senderDid: string
  timestamp: number
  eventId: string
  ephemeral?: boolean
}

interface EventEnvelope {
  type: string
  data: unknown
  meta: EventMeta
  tags?: string[]
  _mediatorEventId?: string
}

interface IdentityState {
  did: string
  alias: string
  mediatorDid: string
  mediatorEndpoint: string
  keys: DecentrlIdentityKeys
  mediatorContract: SignedCommunicationContract | null
}

interface SerializedIdentity {
  did: string
  alias: string
  mediatorDid: string
  mediatorEndpoint: string
  keys: { signing: SerializedKeyPair; encryption: SerializedKeyPair; storageKey: string }
  mediatorContract: SignedCommunicationContract | null
}

interface StoredSignedContract {
  id: string
  participantDid: string
  participantAlias?: string
  signedCommunicationContract: SignedCommunicationContract
  rootSecret: string
  createdAt: number
  status: 'active' | 'expired' | 'superseded'
}

interface PendingContractRequest {
  id: string
  senderDid: string
  encryptedPayload: string
  requestorEphemeralPublicKey: string
}

class DecentrlSDKError extends Error {
  code: DecentrlSDKErrorCode
  details?: unknown
}

type DecentrlSDKErrorCode =
  | 'IDENTITY_NOT_INITIALIZED'
  | 'IDENTITY_ALREADY_EXISTS'
  | 'CONTRACT_NOT_FOUND'
  | 'SCHEMA_VALIDATION_FAILED'
  | 'UNKNOWN_EVENT_TYPE'
  | 'SYNC_FAILED'
  | 'PUBLISH_FAILED'
  | 'QUERY_FAILED'
  | 'QUERY_NOT_SUPPORTED'
  | 'MEDIATOR_ERROR'
  | 'NO_TRANSPORT'