README.md

@atproto/xrpc: atproto HTTP API Client

TypeScript client library for talking to atproto services, with Lexicon schema validation.

Usage

import { LexiconDoc } from '@atproto/lexicon'
import xrpc from '@atproto/xrpc'

const pingLexicon: LexiconDoc = {
  lexicon: 1,
  id: 'io.example.ping',
  defs: {
    main: {
      type: 'query',
      description: 'Ping the server',
      parameters: {
        type: 'params',
        properties: { message: { type: 'string' } },
      },
      output: {
        encoding: 'application/json',
        schema: {
          type: 'object',
          required: ['message'],
          properties: { message: { type: 'string' } },
        },
      },
    },
  },
}
xrpc.addLexicon(pingLexicon)

const res1 = await xrpc.call('https://example.com', 'io.example.ping', {
  message: 'hello world',
})
res1.encoding // => 'application/json'
res1.body // => {message: 'hello world'}
const res2 = await xrpc
  .service('https://example.com')
  .call('io.example.ping', { message: 'hello world' })
res2.encoding // => 'application/json'
res2.body // => {message: 'hello world'}

const writeJsonLexicon: LexiconDoc = {
  lexicon: 1,
  id: 'io.example.writeJsonFile',
  defs: {
    main: {
      type: 'procedure',
      description: 'Write a JSON file',
      parameters: {
        type: 'params',
        properties: { fileName: { type: 'string' } },
      },
      input: {
        encoding: 'application/json',
      },
    },
  },
}
xrpc.addLexicon(writeJsonLexicon)

const res3 = await xrpc.service('https://example.com').call(
  'io.example.writeJsonFile',
  { fileName: 'foo.json' }, // query parameters
  { hello: 'world', thisIs: 'the file to write' }, // input body
)

License

This project is dual-licensed under MIT and Apache 2.0 terms:

• MIT license (LICENSE-MIT.txt or http://opensource.org/licenses/MIT)
• Apache License, Version 2.0, (LICENSE-APACHE.txt or http://www.apache.org/licenses/LICENSE-2.0)

Downstream projects and end users may chose either license individually, or both together, at their discretion. The motivation for this dual-licensing is the additional software patent assurance provided by Apache 2.0.