# @canvas-js/interfaces

> This package exports TypeScript types for Canvas messages and other interfaces.

Latest version **0.16.1** (published 2025-07-30) · 0 weekly downloads

## Install

```sh
npm install @canvas-js/interfaces
pnpm add @canvas-js/interfaces
yarn add @canvas-js/interfaces
bun add @canvas-js/interfaces
```

## Health

**Score 35/100 (D)** — status: maintenance-mode.

Positive: has types; esm support; no vulnerabilities.

Warnings: low downloads; pre 1.0.

Negative: stale; low maintenance score.

## Facts

| | |
|---|---|
| Version | 0.16.1 |
| Published | 2025-07-30 |
| First published | 2022-06-09 |
| Weekly downloads | 0 |
| TypeScript types | bundled |
| Module format | ESM + CommonJS |
| Dependencies | 0 |
| Unpacked size | 9 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| Author | Canvas Technologies, Inc. |
| Maintainers | joelg, raykyri, rjwebb |

## Links

- npm: https://www.npmjs.com/package/@canvas-js/interfaces
- npm.io page: https://npm.io/package/@canvas-js/interfaces

## Recent versions

- 0.16.1 (latest) — 2025-07-30
- 0.16.0-next.9 (next) — 2025-07-13
- 0.10.0-beta.3 (beta) — 2024-06-27
- 0.10.0-alpha.1 (alpha) — 2024-05-21
- 0.8.26-main-488c798d (main) — 2024-02-15
- 0.16.0 — 2025-07-08
- 0.16.0-next.8 — 2025-06-26
- 0.16.0-next.7 — 2025-06-25
- 0.16.0-next.6 — 2025-06-25
- 0.16.0-next.5 — 2025-06-18
- 0.16.0-next.4 — 2025-06-18
- 0.16.0-next.3 — 2025-06-13
- 0.16.0-next.2 — 2025-06-13
- 0.16.0-next.1 — 2025-06-13
- 0.16.0-next.0 — 2025-06-13
- … 247 more at https://npm.io/package/@canvas-js/interfaces/versions

## README

# @canvas-js/interfaces

This package exports TypeScript types for Canvas messages and other interfaces.

## Table of Contents

- [Installation](#installation)
- [API](#api)
  - [Signatures](#signatures)
  - [Signers](#signers)
  - [Messages](#messages)
  - [Actions](#actions)
  - [Sessions](#sessions)
  - [Session signers](#session-signers)
  - [Utility types](#utility-types)
    - [Awaitable](#awaitable)

## Installation

```
npm i @canvas-js/interfaces
```

## API

### Signatures

```ts
import type { CID } from "multiformats"

export type Signature = {
  publicKey: string
  signature: Uint8Array
  cid: CID
}
```

### Signers

```ts
import type { Signature } from "./Signature.js"

export interface Signer<T = any> {
  sign(value: T): Signature
}
```

### Messages

```ts
export type Message<Payload = unknown> = {
  topic: string
  clock: number
  parents: string[]
  payload: Payload
}
```

### Actions

```ts
export type Action = {
  type: "action"

  /** DID of the user that authorized the session (e.g. "did:pkh:eip155:1:0xb94d27...") */
  address: string

  name: string
  args: any

  context: {
    timestamp: number
    blockhash?: string
  }
}
```

### Sessions

```ts
export type Session<AuthorizationData = any> = {
  type: "session"

  /** DID of the user that authorized the session (e.g. "did:pkh:eip155:1:0xb94d27...") */
  address: string

  /** did:key URI of the ephemeral session key used to sign subsequent actions */
  publicKey: string

  /** signer-specific session payload, e.g. a SIWE message & signature */
  authorizationData: AuthorizationData

  context: {
    blockhash?: string
    duration?: number
    timestamp: number
  }
}
```

### Session signers

```ts
import type { Signer } from "./Signer.js"
import type { Message } from "./Message.js"
import type { Session } from "./Session.js"
import type { Action } from "./Action.js"
import type { Awaitable } from "./Awaitable.js"

export interface SessionSigner extends Signer<Action | Session> {
  match: (chain: string) => boolean

  /**
   * Produce an signed Session object, which authorizes `session.publicKey`
   * to represent the user `${session.chain}:${session.address}`.
   *
   * The signature is stored in `session.data`, and the entire Session
   * object is then signed using the session-key, and appended to our message log.
   */
  getSession: (topic: string, options?: { chain?: string; timestamp?: number }) => Awaitable<Session>

  /**
   * Verify that `session.data` authorizes `session.publicKey`
   * to take actions on behalf of the user `${session.chain}:${session.address}`
   */
  verifySession: (session: Session) => Awaitable<void>
}
```

### Utility types

#### `Awaitable`

```ts
export type Awaitable<T> = T | Promise<T>
```

---
_Source: https://npm.io/package/@canvas-js/interfaces · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._