{"id":16905,"library":"ssb-typescript","title":"Secure Scuttlebutt TypeScript Types","description":"ssb-typescript provides comprehensive TypeScript type definitions for the Secure Scuttlebutt (SSB) protocol, enabling developers to build SSB applications with strong type safety. It defines core SSB concepts such as `FeedId`, `MsgId`, `BlobId`, and various message interfaces like `Msg`, `UnboxedMsg`, and `Content` (which is a union of specific content types like `PostContent`, `ContactContent`, `VoteContent`, `BlogContent`, and more). The current stable version is 2.8.0. As a type-only package, its release cadence is typically driven by changes in the underlying SSB protocol or common application patterns, rather than frequent functional updates. Its key differentiator is providing a standardized, community-maintained set of types for the decentralized SSB ecosystem, helping to ensure interoperability and reduce development errors when working with SSB data structures.","status":"active","version":"2.8.0","language":"javascript","source_language":"en","source_url":"https://github.com/ssbc/ssb-typescript","tags":["javascript","ssb","typescript"],"install":[{"cmd":"npm install ssb-typescript","lang":"bash","label":"npm"},{"cmd":"yarn add ssb-typescript","lang":"bash","label":"yarn"},{"cmd":"pnpm add ssb-typescript","lang":"bash","label":"pnpm"}],"dependencies":[],"imports":[{"note":"Msg is a named export, not a default export. Ensure you destructure it correctly.","wrong":"import Msg from 'ssb-typescript';","symbol":"Msg","correct":"import { Msg } from 'ssb-typescript';"},{"note":"These are fundamental string literal types for SSB identifiers.","symbol":"FeedId, MsgId, BlobId","correct":"import { FeedId, MsgId, BlobId } from 'ssb-typescript';"},{"note":"This package exports only TypeScript type declarations. There are no runtime values to import via CommonJS `require`.","wrong":"const Content = require('ssb-typescript').Content;","symbol":"Content, PostContent","correct":"import { Content, PostContent } from 'ssb-typescript';"}],"quickstart":{"code":"import { Msg, PostContent, FeedId, MsgId, Content } from 'ssb-typescript';\n\n// Example FeedId, MsgId, BlobId (standard SSB identifiers)\nconst exampleFeedId: FeedId = '@HXjeG7t2p8zU9gT0t2p8zU9gT0t2p8zU9gT0t2p8zU9gT0.ed25519';\nconst exampleMsgId: MsgId = '%mS3G7t2p8zU9gT0t2p8zU9gT0t2p8zU9gT0t2p8zU9gT0.sha256';\nconst exampleRootMsgId: MsgId = '%mS3G7t2p8zU9gT0t2p8zU9gT0t2p8zU9gT0t2p8zU9gT0.sha256';\n\n// Define a PostContent message\nconst postContent: PostContent = {\n  type: 'post',\n  text: 'Hello, Secure Scuttlebutt! This is a test post from ssb-typescript.',\n  channel: 'testing',\n  mentions: [], // Empty array for no mentions\n  root: exampleRootMsgId,\n};\n\n// Define an SSB Message wrapper\nconst ssbMessage: Msg<PostContent> = {\n  key: exampleMsgId,\n  value: {\n    previous: '%prevMsgId.sha256',\n    author: exampleFeedId,\n    sequence: 123,\n    timestamp: 1678886400000, // UTC epoch milliseconds\n    hash: 'sha256',\n    content: postContent,\n    signature: 'fake-signature-string-here',\n  },\n  timestamp: 1678886400000,\n};\n\n// Demonstrate generic Content type usage\nconst genericContent: Content = {\n    type: 'contact',\n    contact: exampleFeedId,\n    following: true\n};\n\nconsole.log('Example SSB Post Message:', JSON.stringify(ssbMessage, null, 2));\nconsole.log('Example generic Content:', JSON.stringify(genericContent, null, 2));\n\n// To compile and run this example:\n// 1. Install dependencies: `npm install typescript ssb-typescript ts-node`\n// 2. Save the code as `example.ts`.\n// 3. Execute: `npx ts-node example.ts`","lang":"typescript","description":"This quickstart demonstrates how to define common SSB types like `FeedId`, `MsgId`, `PostContent`, and the full `Msg` interface using the provided type definitions."},"warnings":[{"fix":"Review the type definitions in the `ssb-typescript` source or the generated `.d.ts` files after upgrading. Update your application's data structures to match the latest interfaces.","message":"The `Msg` and `Content` interfaces have evolved over time to reflect changes in the SSB protocol. If upgrading from very old versions, verify the structure of message content and metadata, especially around private messages and new content types.","severity":"breaking","affected_versions":">=2.0.0"},{"fix":"Implement runtime validation or custom type guards for `mentions` arrays. Consider declaring a more specific type if your application has a consistent structure for mentions.","message":"The `mentions` property in `PostContent` and `BlogContent` is typed as `Array<any>`. This means TypeScript will not enforce types within this array, potentially leading to runtime errors if not carefully validated at the application level.","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"Use type assertions (`as PostContent`), `instanceof` checks (if applicable to your runtime data), or switch statements with `content.type` to narrow down the `Content` type. For `Msg` objects, declare `Msg<SpecificContentType>`.","message":"The `Content` union type is very broad, encompassing all known SSB message content types. If you need to work with a specific content type (e.g., `PostContent`), always use type guards or explicit generics (`Msg<PostContent>`) to narrow the type and enable full type safety.","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"Keep `ssb-typescript` version synchronized with the versions of other core SSB libraries you are using. Consult the change logs for both `ssb-typescript` and the related SSB libraries during upgrades.","message":"Using `ssb-typescript` with vastly different versions of SSB client libraries or schema definitions (e.g., `ssb-db`, `ssb-client`) can lead to type mismatches where the types don't accurately reflect the runtime data structures. This is particularly true if the SSB ecosystem itself undergoes significant protocol changes.","severity":"gotcha","affected_versions":">=1.0.0"}],"env_vars":null,"last_verified":"2026-04-22T00:00:00.000Z","next_check":"2026-07-21T00:00:00.000Z","problems":[{"fix":"Ensure the package is installed: `npm install ssb-typescript` or `yarn add ssb-typescript`. Verify your `tsconfig.json` includes `node_modules/@types` or has appropriate `typeRoots`.","cause":"The `ssb-typescript` package is not installed, or TypeScript cannot locate its type definitions.","error":"TS2307: Cannot find module 'ssb-typescript' or its corresponding type declarations."},{"fix":"Add all required properties (e.g., `mentions?: Array<any>;`) to your object, even if they are empty arrays or `undefined`, or ensure optional properties are explicitly set. Check the `PostContent` interface for exact requirements.","cause":"An object being assigned as `PostContent` is missing required properties, or properties are of the wrong type, according to the `PostContent` interface definition.","error":"TS2322: Type '{ type: \"post\"; text: string; }' is not assignable to type 'PostContent'. Property 'mentions' is missing in type '{ type: \"post\"; text: string; }' but required in type 'PostContent'."},{"fix":"While `FeedId` is an alias for `string`, TypeScript might enforce stricter checks depending on context or other utilities. Ensure the string format is correct (e.g., starts with `@` for `FeedId`). If you are certain about the string's correctness, you can use a type assertion: `someString as FeedId`.","cause":"Attempting to assign a plain string literal or `string` variable to a type like `FeedId`, `MsgId`, or `BlobId`, which are typically branded string types for stronger type checking.","error":"TS2345: Argument of type 'string' is not assignable to parameter of type 'FeedId'."},{"fix":"Ensure you are constructing a complete `Msg` object (which includes `key`, `value`, `timestamp`) and placing your `PostContent` inside the `value.content` field when a full message is required.","cause":"You are trying to use a `PostContent` object where a full `Msg` interface is expected. `PostContent` is only the `content` property of a `Msg`.","error":"TS2740: Type 'PostContent' is missing the following properties from type 'Msg<Content>': key, value, timestamp."}],"ecosystem":"npm","meta_description":null}