Resources

Changelog

What changed in each version of @awesomate/sdk.

Every version of @awesomate/sdk, newest first. The format follows Keep a Changelog. Until 1.0, a minor version can change behaviour; each entry says when it does.

#[0.27.0] - 2026-10-09

#Added

• db.whoami() returns key: whose key it is. account_owner acts as the owner; person is a team member's own key, which does only what that person can do in the hub (level view or full).

#[0.26.0] - 2026-10-09

#Added

• db.whoami(): the account, its plan, the token's scopes and expiry, and which features the account has, each with the sentence to say when it does not. See Server and n8n.
• db.metrics(), db.series(metric, options), db.datasets() and db.dataset(id): what the contact list can be measured by, one figure over time, and the dataset aggregate() reads. See Numbers.
• db.appUsers.list(), invite(email, { role }) and update(id, { role, disabled, contactId }): the people who sign in to the account's apps. Changes need Pro. See App people.
• db.bookings.setup(): the calendars and services, so openTimes() and book() have keys to use.
• db.tasks.decisions({ scope }) and db.tasks.decisionRecord(taskId): the decisions on the Tasks page, read only. Deciding stays a person's tap in the hub.
• db.supportDesk.status(), tickets({ status, limit }) and ticket(id): the account's own support desk, read only. See Support desk.
• db.knowledge.ask(question, { session, filters }), search(options) and data(query): a cited answer, instant search and Your numbers, from a server. See Knowledge from a server.
• db.addAttribute(kind, attribute) and db.archiveAttribute(kind, key), so a kind defined from code can be changed from code.
• db.assistantUsage(appId), db.businessCatalogue(), db.files.extract(path) and db.files.capabilities().
• verifyAppToken(token, { appId }): check an app's access token on your own server against the hub's keys. app.auth.me(): the signed-in person read fresh, with the app's settings.
• AwesomateError now carries reason, feature, missingScopes, upgrade and requiredPlan when the hub sent them. Type AwesomateErrorDetails.
• Fields the hub already sent: TaskCard.type, openLabel, ownerOnly, action, passedBy and task.raisedBy; schema() now has its full type (Schema): each kind's description, sections, hidden fields, grammar and examples, each column's description, section, field type, choices and whether it sorts, and limits, default_timezone or (for an app key) access.
• Types WhoAmI, Schema, SchemaKind, SchemaColumn, Metric, MetricSeries, Dataset, AppPerson, AssistantUsage, BusinessCatalogue, BookingSetup, BookingCalendar, BookingServiceSetup, DecisionBoard, DecisionCard, DecidedDecision, TaskCardAction, SupportDeskStatus, SupportTicketStatus, SupportTicketSummary, SupportTicket, KnowledgeAnswer, KnowledgeFilters, KnowledgeSearchOptions, KnowledgeSearchResult, KnowledgeSearchHit, KnowledgeDataQuery, FilesCapabilities, AppMe and AppTokenClaims.

#Changed

• Three new error codes. A refusal that used to be forbidden is now feature_unavailable (the account does not have the feature), upgrade_required (a plan floor, including the hub's plan_required) or scope_missing (the token lacks a scope). If you branched on code === 'forbidden' for these, branch on the new codes; serverCode keeps the hub's code.
• Every way the hub says "switched off in Privacy" is now consent_blocked: consent_required, consent_off, consent_missing and Knowledge's consent_required: true joined consent_denied and files_consent_off.
• A refusal whose error is a code and whose message is the sentence (Knowledge's shape) now has the sentence as message and the code as serverCode (it was empty before).
• An app key's call that met conflict now retries on its own route instead of failing forbidden.
• verifyAppToken refetches the hub's keys for an unknown key id at most every 30 seconds, and a non-JSON key answer is unavailable.
• tasks.record() returns TaskRecord & { kind: 'task' }; TaskRecord.kind is 'task' | 'decision'.
• The bookings client's fallback message for a refusal with no words is now "The hub answered .", as the other clients'.

#Fixed

• An app key's schema() now carries the owner's descriptions and sections, as the account token's does (the hub left them out).

#[0.25.0] - 2026-10-07

#Added

• db.recordEvent({ event, email, record?, occurredAt?, key?, firstName?, lastName? }): tell Contacts something happened to someone, so any email series waiting for that event starts or stops. Never changes consent; the same key is recorded once. See Email series events.
• db.bookings: the account's bookings for staff screens: list(), get(), openTimes(), book(), cancel(), move() and outcome(). Writes need Support Plus and Bookings on the account. See Bookings, Staff screens.
• db.businessDocuments() and db.businessDocument(kind): the business's brand guide, voice guide, brand from its website and business summary.
• db.tasks.bringBack(id), db.tasks.record(id) and db.tasks.cancelNotNow(key).
• db.files.trash() and db.files.emptyTrash({ olderThanDays }).
• Types StaffBooking, StaffBookingRequest, BookingPageLook, SeriesEvent, BusinessDocument, BusinessDocumentSummary, BusinessDocumentKind, KindAccess, TaskRecord, TaskRecordStep and TrashEntry.
• Fields the hub already sent: TaskBoard.canChooseScope, canGive, unavailable, hasTeam and decided[].canBringBack; BookableService.cancel_cutoff_hours; ManagedBooking.priceText; RecipeDescription.run_by; KindDescription.access and each attribute's visible_to; views.for_app.
• AttributeSpec.visible_to and KindSpec.access, which defineKind() already accepted.
• bookings.booking(token) now also returns look (the business's website, logo and colour), which the hub already sent.

#Changed

• get() on both clients answers null, without a request, for an id that is not a UUID. It used to send the request and throw a validation error, though its doc said null.
• bookings.book(), cancel() and move() now name every conflict reason the hub can give: too_many_seats, too_many_open, monthly_limit and too_late were missing.

#[0.24.0] - 2026-10-06

#Changed

• db.businessMap() now returns the map in the words the owner sees in the hub, from /api/my-business/v2/map. This changes its shape: rename as below, or call db.businessMapV1() for the old shape while you move.

#Added

• db.businessMapRoles(): every role in one line each, and db.businessMapRole(slug): one role with the line each helper's instructions carry.
• Types BusinessMapRole, BusinessMapDepartment, BusinessMapSubDepartment, BusinessMapRoleSummary, BusinessMapRoleDetail. BusinessMap.settings.oneBrainCategory, which the hub already sent.

#Deprecated

• db.businessMapV1() and the types BusinessMapV1, BusinessMapDivision, BusinessMapJob, BusinessMapPathStepV1. The v1 routes are removed once they have gone 30 days unused, and not before 2026-11-06.

#[0.23.0] - 2026-10-06

#Added

• db.businessMap(): each division's noHatYet, the people on the map who wear no hat yet. They sit in Form (division 1) for display, so the list is empty for every other division.

#[0.22.0] - 2026-10-06

#Added

• db.businessMap(): each hat's quarterly priorities (quarter, title, owner, status, due date) and the map's quarter (this quarter, UTC). Type BusinessMapPriority.

#[0.21.0] - 2026-10-05

#Added

• db.businessMap(): each job's headsDepartment, and each division's departments[].runBy and headJob, so a department-level KPI can be shown against the person responsible for the department. A job that runs its division (headsDivision) now sits above its departments and has no departmentNo, except the owner's own job.

#[0.20.0] - 2026-10-05

#Added

• app.ask(question): a typed question to the app's agent, answered from the business's content with sources, as the signed-in person (their customer groups apply). Returns { status, answer, sources, questionNotice }; show questionNotice with a person's first answer. See Ask by text.
• Type AgentAnswer.

#[0.19.0] - 2026-10-05

#Added

• db.tasks: the account's Tasks board from your server or an n8n workflow: board(), give() a task to someone on the account, update(), done(), drop(), and notNow() / passOn() for any card. Account token only. See Tasks.
• Types TaskBoard, TaskCard, TaskPerson and GiveTask.

#[0.18.1] - 2026-10-05

#Fixed

• app.here() on a record another part of the page already has open (a thread and a sidebar on the same job): the first one stopped hearing who was there and its typing() did nothing, and when the second called leave() the hub was told this person had left while the first was still on the record. Now every part hears onPeople, a part that opens the record later hears who was last there, typing shares one clock per record, and the record closes only when the last part leaves. It counts once towards the 5 records a connection can have open.

#[0.18.0] - 2026-10-05

#Changed

• db.files.makePrivate(): a file made private, deleted or replaced now stops being served from its public address within seconds, because the hub clears Cloudflare's copy. Before, the old copy could keep loading for up to 4 hours. A browser that already opened the file may still keep its own copy for a while.

#[0.17.0] - 2026-10-05

#Added

• createBookingsClient({ key }): a business's own booking page for visitors who are not signed in. services() and openTimes() list what can be booked and when, book() books (the customer gets an email with an invite and a link to change or cancel), and booking(), openTimesToMove(), move() and cancel() work from that link. Uses the booking key (bk_) from Contacts, Bookings, so it works on every plan, from the sites the key lists. See Bookings.
• manageTokenFrom(url): the token in a booking's manage link.

#[0.16.0] - 2026-10-05

#Added

• db.files: the account's Files (the folders on its automation account) from your server: list, search, usage, upload, download, mkdir, move, makePublic, makePrivate, remove. Files in public/ come back with a public_url. Needs the account's token with files:read or files:write; an app's server key is refused. See Files and uploads.
• app.files: people signed in to your app can attach files when the account switches uploads on for the app: mode(), upload() (up to 10 MB, answers a handle to keep in a record) and download(handle).
• Types FileEntry, FilesUsage, AppFile and FileBody.

#Changed

• A 411, 413 or 415 from the hub now reads as validation, and consent_denied as consent_blocked.

#[0.15.0] - 2026-10-05

#Added

• db.businessMap() now returns path: how a customer moves through the business, step by step, with the division, the job that looks after each step, who that is, and the hand-off. When the owner has not set one, it is the path suggested for their kind of business (path.stored is false).
• Each job's proceduresTag (such as job:quotes), the tag its procedures carry in 1Brain, and each division's oneBrainDepartments.
• Gap kinds procedure_first (a job something helps with, but nothing says what it covers), path_missing and path_unowned.

#[0.14.0] - 2026-10-05

#Added

• db.businessMap(): the business map, read only. The seven divisions, the jobs in each and who holds them, which agents and automations help which job and how far each may go, and what is missing, most important first. Account token only. See Your business map.

#[0.13.0] - 2026-10-04

#Added

• app.voiceAgent() and app.voiceSession(): let the people signed in to your app talk by voice to the agent the app names, with the hub's AwesomateAgent widget. See Talk by voice.
• AwesomateError.personMessage: the sentence to show the person using your app, when the hub sends one (a refused voice call, for example).
• The query filter types TextOps, NumberOps, BoolOps and ListOps are exported.
• Documentation at https://hub.awesomate.ai/docs/sdk/, with a reference generated from this package's code, and llms.txt for AI tools.

#Fixed

• A filter on a choice column can name several of its choices: { status: { in: ['open', 'quoted'] } } was a type error with generated types, because the filter type was worked out once per choice. Found by the new docs build, which type-checks every example.
• VERSION reports this package's real version. It had said 0.7.0 since version 0.8.0, and the server client sends it with every request. The docs build now fails if they differ.
• The voice methods were merged in the hub on 2026-10-04 but missed npm: 0.12.0 had already been published from another change. They ship here.

#[0.12.0] - 2026-10-04

#Added

• db.business() and db.businessSuggestions(): read what Awesomate knows about the business (name, what it does, voice, colours, how customers reach it), with where each detail came from. Account token only.

#[0.11.0] - 2026-10-04

#Added

• app.here(recordId, onPeople, onError?): who else has a record open, who is typing, and the app's assistant while it writes a reply. Returns typing() and leave(). See Who's here and typing.

#[0.10.0] - 2026-10-04

#Changed

• A live connection in a browser tells the hub whether the tab is in front. Reply emails now wait only while someone is actually looking at the app; a tab left open in the background no longer holds them back.

#[0.9.0] - 2026-10-04

#Added

• app.call(recipe, args): a signed-in person runs a write recipe the account opened to their role, such as accepting their own quote. See Let customers take an action.

#[0.8.0] - 2026-10-03

#Added

• app.lookupCustomers({ q | ids, limit }): staff in the roles an app allows find a customer and put a record under them.

#[0.7.0] - 2026-10-03

#Added

• createClient accepts an app server key (ak_...) as well as the account's token. A key reads and writes records of its own kinds and runs saved queries and recipes; it cannot change the account's shape.

#[0.6.0] - 2026-10-03

#Added

• auth.onSignInError(listener): hear when a sign-in link has expired or was already used.
• The handleSignInLinks option (on by default in a browser).

#Changed

• A sign-in link signs the person in by itself, on page load or when it arrives in a tab that is already open. Calling auth.completeSignIn() as well is safe, and returns the same sign-in.

#[0.5.0] - 2026-10-03

#Added

• app.live(kind, options, onRows): a list kept current over one WebSocket, re-run as the person on every change. See Lists that keep themselves current.

#[0.4.0] - 2026-10-03

#Added

• createAppClient({ publishableKey }): the app client. Your app's people sign in by email link (auth.signInWithLink, auth.completeSignIn, auth.user, auth.onChange, auth.signOut, auth.accessToken) and then query, get, write and archive as themselves, inside the account's rules.
• signInTokenFrom(url).

#[0.3.0] - 2026-10-03

#Added

• Saved queries: db.queries(), db.saveQuery(), db.run(), db.archiveQuery().
• Write recipes: db.recipes(), db.saveRecipe(), db.call(), db.archiveRecipe().
• Generated types cover saved queries' parameters and rows, and recipes' arguments.

#[0.2.0] - 2026-10-03

#Added

• App kinds: db.kinds(), db.defineKind(), db.write(), db.archive().

#[0.1.0] - 2026-10-03

#Added

• createClient({ token }): read your contact list with query, queryAll, get, aggregate and schema.
• npx @awesomate/sdk types: TypeScript types generated from your own account's fields.