Add a source

You have a service, such as a calendar, a meeting app or a file store, and you want its records in the shared WireCat store so that search and every other tool can use them. This page shows the steps: choose the entity your records feed, write them as source records, let cli-core link them, and keep secrets out. It assumes you know the concepts.

StepsCopy Anchor Link

1. Choose the entity. Decide what the owner means by your records: a person, an event or a document. Your records are source records of that entity. If nothing fits, the record type is a new core entity and needs a cli-core change, not a table of your own.
2. Write through cli-core. Save records through cli-core's store areas, never with your own SQL (WC-STORE-5). If an area lacks the method you need, add it to cli-core with its test.
3. Key by the provider's id. Each record has its account_id and the provider's id in external_id. Saving the same record again updates it instead of adding a copy.
4. Use the standard names. A field you filter, sort, join or list on is a column with a standard name: title, url, starts_at, ends_at, external_updated_at. Times are UTC milliseconds. Anything else goes in metadata, allow-listed (WC-DATA-4, WC-DATA-5).
5. Let matching link them. cli-core links your record to its entity by a rule: the same key, a shared id such as a calendar's ical_uid, a join link or an exact content hash. Two equal candidates make no link.
6. Soft-delete what disappears. When the provider stops returning a record, it gets deleted_at. Its entity and the owner's links stay (WC-DATA-7).

Worked example: Zoom meetingsCopy Anchor Link

The zm tool brings Zoom meetings into the store this way today:

• each meeting is a meetings row, a source record, saved through cli-core's meeting store;
• account_id is the Zoom account and external_id is Zoom's meeting id, unique together;
• event_id points at the event, the entity, and is set by event linking;
• the participants are identities, so a Zoom participant and the same person in Telegram can meet at one person.

A recording that arrives later finds the same row by its key and updates it.

Never storeCopy Anchor Link

• tokens, passwords and keys (security rules);
• meeting passcodes, PINs and the query string of a join link;
• a provider's raw response; keep only allow-listed fields.

Register your providerCopy Anchor Link

Each time your tool runs, it records its provider in the store: its name, kind, aliases and command. Every other tool then knows the new source without a cli-core release. Rows of a provider no tool has recorded are skipped and reported, never searched as messages.

import { openStore } from "@wirecat/cli-core/store"

const store = await openStore()
await store.accounts.registerProvider({ name: "acme", kind: "meetings", aliases: ["acme"], command: "acme" })

kind is what search reads your records as: messages, mail, notes, documents, meetings or events.

What breaks if you skip thisCopy Anchor Link

Without external_id, each sync adds the same record again. Without soft delete, a failed sync erases what the owner linked or wrote. Without the shared store areas, the next cli-core migration breaks your tool.

Next: Keep your own data.