> For the complete documentation index, see [llms.txt](https://www.conserver.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://www.conserver.io/vcon-js-library.md).

# vCon-JS Library

What vcon-js 0.5.2 covers, how it differs from the Python library, and where to start.

`vcon-js` is the TypeScript and JavaScript implementation of the vCon specification. It is a peer to the [Python `vcon` library](https://www.conserver.io/vcon-library.md) and targets [`draft-ietf-vcon-vcon-core`](https://datatracker.ietf.org/doc/draft-ietf-vcon-vcon-core/) with syntax parameter `"0.4.0"`.

> **Current version:** `vcon-js` **0.5.2** (npm). Install with `npm install vcon-js`. Node 18 or later. Source and changelog: [vcon-dev/vcon-js](https://github.com/vcon-dev/vcon-js).

## When to use vcon-js

* **vcon-js** for Node services, edge functions, Cloudflare Workers, browser code, or any TypeScript codebase that reads or writes vCons.
* **Python `vcon`** for data pipelines, ML preprocessing, and conserver links.

Both libraries write the same JSON structure and each reads the other's output. They do not produce identical bytes. Python 0.10 writes the tags attachment body as a list and drops empty `meta`; vcon-js writes tags as a JSON object. Treat the JSON as interchangeable and do not compare serialized strings across libraries. Field rules live in the [field reference](https://www.conserver.io/vcons/field-reference.md).

## What 0.5.2 covers

* Classes: `Vcon`, `Party`, `Dialog`, `Attachment`, `PartyHistory`. `Analysis` is a type, passed as a plain object to `addAnalysis`.
* Current core-draft surface: `recording-set` dialogs (`recordings`, `recording_set`), analysis `attachment` reference with `dialog` optional, party `type`, `org`, `dept`, and a typed `provenance` parameter on dialog and analysis.
* Spec-correct names: `amended`, `critical`, `purpose` on attachments, `mediatype`. `vcon: "0.4.0"` is set for you.
* Inline and external content: `body` plus `encoding`, or `url` plus `content_hash` (format `sha512-<base64url>`, checked by `validate()`). 0.5.2 requires the `content_hash` with a `url`. vcon-js `main` (the upcoming 1.0.0, not yet on npm) allows a `url` without one on dialog, attachment, and analysis, following the WG direction on [core issue #40](https://github.com/ietf-wg-vcon/draft-ietf-vcon-vcon-core/issues/40), and still rejects a malformed hash.
* `addAnalysis` accepts an object or array body, serializes it to a string, and sets `encoding: "json"`.
* Tags through `addTag`, `getTag`, and the `tags` getter, stored as one `purpose: "tags"` attachment with `start` set.
* Declared extensions through `addExtension`, `addCriticalExtension`, `hasExtension`, `isCriticalExtension`.
* Finders: `findPartyIndex`, `findDialog`, `findAttachmentByPurpose`, `findAnalysisByType`.
* Per-class validators: `Dialog.validate()`, `Attachment.validate()`, `Party.validate()`, `PartyHistory.validate()`.
* Schema conformance: the test suite validates emitted vCons against the core JSON Schema.

## What it does not do

* **No per-extension helpers.** Python has `add_lawful_basis_attachment()`, `add_wtf_transcription_attachment()`, and `add_wtf_transcription_analysis()`. In vcon-js you build the attachment or analysis yourself with `addAttachment` or `addAnalysis`. See [Lawful Basis](https://www.conserver.io/extensions/lawful-basis.md) and [WTF Transcription](https://www.conserver.io/extensions/wtf-transcription.md) for the shapes. Extension parameters round-trip untyped, except `provenance`.
* **No signing or encryption.** Version 0.5.2 removed the unused `jose` and `jsonwebtoken` dependencies and the `Signature` type and the `signature`, `signatures`, and `payload` fields on `VconData`. Key management and JWS handling are the caller's job. The per-dialog `alg` and `signature` fields for url-referenced content are unchanged.
* **No whole-vCon validator and no content-hash helper.** Compute hashes yourself (the [quickstart](https://www.conserver.io/vcon-js-library/quickstart.md) shows `node:crypto`).
* **No extension-specific search helpers.** Filter `attachments` and `analysis` with `findAttachmentByPurpose` or `Array.filter`.

## Examples

The repository ships runnable TypeScript examples under [`examples/`](https://github.com/vcon-dev/vcon-js/tree/main/examples): a text chat, a call recording with external media, a video conference, and an inline recording. Run them with the `npm run example:*` scripts in the repo.

## In this section

* [Quickstart](https://www.conserver.io/vcon-js-library/quickstart.md) builds a vCon with parties, dialog, analysis, a lawful basis attachment, and tags.
* [API Reference](https://www.conserver.io/vcon-js-library/api-reference.md) lists every exported class, method, and type.
* [LLM Guide](https://www.conserver.io/vcon-js-library/llm-guide.md) is a rule sheet to paste into a model's context when it generates vcon-js code.

## See also

* [Python vCon Library](https://www.conserver.io/vcon-library.md)
* [vCon-C Library](https://www.conserver.io/vcon-c-library.md)
* [Extensions](https://www.conserver.io/extensions.md)


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://www.conserver.io/vcon-js-library.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.
