SDK TypeScript

Пакет @basedb/sdk викликає REST API з TypeScript або JavaScript: типізовані рядки, усі сторінки, файли, відмови з їхнім кодом. Жодної залежності: стандартний fetch, під Node 18 і новіше, Deno, Bun або в браузері.

npm install @basedb/sdk

Типи ваших таблиць

Команда читає опис ваших баз і записує їхні типи у файл вашої програми:

BASEDB_URL=https://basedb.exemple.fr BASEDB_TOKEN=bdb_… npx @basedb/sdk types --out src/basedb.ts

Кожна база, яку відкриває токен, — або названі через --base, повторюваний, — а для кожної таблиці три форми: рядок таким, яким basedb його читає, таким, яким його створюють, таким, яким його змінюють. Список вибору стає об’єднанням своїх значень; поле, яке обчислює basedb — формула, підстановка, зведення, кількість, автоматичний номер — читається без можливості запису; обов’язкове поле без значення за замовчуванням вимагається під час створення. Запускайте команду знову, коли таблиці змінюються.

Читання і запис

import { Basedb, BasedbError, filter } from '@basedb/sdk'
import type { Schema } from './basedb.js'

const db = new Basedb<Schema>({ url: 'https://basedb.exemple.fr', token: process.env.BASEDB_TOKEN! })
const opportunites = db.base('b_t4z56fq_ventes').table('opportunites')

const o = await opportunites.create({ titre: 'Audit', montant: 12500, statut: 'nouveau' })
await opportunites.update(o._id, { statut: 'gagne' })

for await (const ligne of opportunites.all({
  filter: filter`statut eq ${'gagne'} and montant gte ${10000}`,
  sort: '-montant',
})) {
  console.log(ligne.titre, ligne.montant)
}

Таблиця, поле чи варіант вибору, якого не існує, — це помилка типу, ще до того, як програма запуститься.

Метод	Роль
list(options)	одна сторінка, і next для наступної
all(options)	усі рядки фільтра, сторінка за сторінкою, у міру читання
first(options), count(filtre)	перший рядок, кількість рядків
get(id)	один рядок
create(valeurs), createMany(lignes)	додати рядок; кілька, усі або жодного
update(id, valeurs)	змінити поля; відсутнє поле лишається таким, null спорожняє його
aggregate({ aggregates, filter, group })	суми, середні, підрахунки за всіма рядками фільтра
comments(id).list(), .add(texte)	коментарі рядка; @згадка сповіщає
upload(champ, octets, { name, type })	завантажити файл, на який рядок потім посилається за його id
db.undo(ligne)	скасувати запис, який зробив цей рядок таким, — відхиляється, якщо він відтоді змінився

• filter записує кожне вставлене значення саме як значення: текст, введений користувачем, лишається текстом, а не частиною фільтра.
• Числа читаються як десятковий текст ("12500.0000000000"), щоб не втратити жодної цифри; записуються числом або текстом.
• Зв’язок читається як { id, display } і записується через _id пов’язаного рядка; links: 'id' читає лише _id.
• Відмова — це BasedbError: її code — стабільний, один на причину, той самий в усіх мовах —, status, details і requestId. Прохання почекати (429) повторюється після затримки, яку вказує basedb.

Середовища

База, яка має кілька середовищ — продакшн, тестування… — зберігає свої назви й типи від одного середовища до іншого. З токеном, створеним на всю базу, environment() націлює на середовище, і той самий код виконується в іншому:

const recette = db.environment('recette')
await recette.base('b_t4z56fq_ventes').table('opportunites').first()

Параметр environment конструктора робить те саме для всього клієнта. SDK надсилає заголовок X-Basedb-Environment; без нього кожна назва бази позначає власне середовище (b_t4z56fq_ventes — це продакшн).

Токен

Токен інтеграції створюється в інтерфейсі: меню ⋯ бази → API та агенти → Токени API і MCP…. Він відкриває одну базу — усі її середовища або лише одне, — читає її рядки, записує їх, якщо створений із правом запису, ніколи не має більше дозволів, ніж особа, яка його створила, і видаляє лише якщо його створено для цього («Читання, запис і видалення»): інакше delete() відхиляється.