Getting started

Welcome to Context Protocol.

🚀 Introduction

Context is an abstraction layer designed to integrate Web3 storage technologies, providing distinctive features that enhance data management. Dive into creation with our SDK, which helps users to organize, read and share public and private data in a sovereign, trusted, and verified way. Saying goodbye to hashes, and embracing domains and documents within the blockchain ecosystem. We empower developers to innovate, providing the tools you need to build groundbreaking applications on top of our platform.

Every data on Context is publicly available, free, and forever for other developers to use locally through our public gateway - i.e. rpc.ctx.xyz/contextprotocol

⚡ Getting started

Install the SDK

Install the Context SDK to your TypeScript project using npm:

npm install @contextprotocol/sdk

Setting Up Your Connection

To use Context, you always need a domain. This domain acts as your namespace within Context, where all your documents will be stored. Then, you'll need to obtain an API key for your domain.

You can claim your domain and generate the API key by creating an account at app.ctx.xyz.

Initialize the SDK:

import { Context } from '@contextprotocol/sdk';

const ctx = new Context({ apiKey: "your_api_key_here" }); // Replace with your API key

🌐 Working with Domains

Domains represent verified and curated entities, such as companies, projects, or individuals.

Fetch Domain Information

Fetch details of a specific domain or the default domain associated with your API key:

// Fetch your domain
const yourDomain = await ctx.domain();

// Fetch a specific domain
const domain = await ctx.domain("domain_name");

Domain Properties

Access and display properties of a domain:

console.log(domain.data.name);
console.log(domain.data.documents);
console.log(domain.data.status);
console.log(domain.data.createdAt);
console.log(domain.data.updatedAt);

📄 Managing Documents

Fetch Documents

Fetch a specific document or template or asset, from any domain:

// Fetch a specific document
const document = await ctx.document("document_path");  // "domain/path/to/file"

Document Properties

Access and display properties of a document:

console.log(document.data.path);
console.log(document.data.versionNumber);
console.log(document.data.data);
console.log(document.data.metadata);
console.log(document.data.templates);
console.log(document.data.type); // Document | Template | Asset
console.log(document.data.txId);
console.log(document.data.createdAt);
console.log(document.data.updatedAt);
console.log(JSON.stringify(document.data));

List Document Versions

Fetch a list of all versions of a document:

const documentVersions = await document.data.versions();

Fetch a Specific Document Version

You can fetch a specific version of a document in two different ways:

// By using the version method of the document:
const document = await ctx.document("document_path");
const documentVersion = await document.data.getVersion("X.Y.Z");

// By specifying the version directly the document path:
const documentInVersionXYZ = await ctx.document("document_path?v=X.Y.Z");

Create a Document

Steps to create a new document within a domain:

const data = YOUR_AWESOME_JSON_DATA;  // JSON data for the document
const templates = ["template_path"];  // Optional array of template paths
const metadata = { name: "Document Name", description: "Document Description", readme: "ctx:domain/files/my_markdown" };  // Optional metadata

const newDocument = await ctx.createDocument("document_path", data, templates, metadata);

Update a Document

Update an existing document:

const updatedData = YOUR_UPDATED_AWESOME_JSON_DATA;  // Updated JSON data
const document = await ctx.document("document_path");
if (!document.success) {
    // Handle error
}
const result = await document.data.update(updatedData);

Adding Metadata to a Document

You can add metadata to a document using the addMetadata method. The metadata object should contain the following (optional) fields: name, description, and readme as shown below:

const metadata = { name: "Document Name", description: "Document Description", readme: "ctx:domain/files/my_markdown" };
await document.data.addMetadata(metadata);

📐 Creating Templates

Define a JSON Schema for a Template

Create a JSON schema directly or from a TypeScript interface:

// Direct JSON Schema definition
const schema = {
  "$schema": "http://json-schema.org/draft-07/schema#",
  "type": "object",
  "properties": {
    "name": {"type": "string", "description": "The name of the organization."},
    "description": {"type": "string", "description": "A brief description of the organization."},
    "website": {"type": "string", "description": "The URL of the organization's website.", "format": "uri"}
  },
  "required": ["name"],
};

// Generate JSON schema from a TypeScript interface
const dataName = 'User';
const myDataType = `interface ${dataName} {
  name: string;
  age: number;
}`;
const schema = generateJsonSchema(dataName, myDataType);

Create a New Template

Use the defined schema to create a new template:

const metadata = { name: "Template Name", description: "Template Description", readme: "Markdown document" };  // Optional metadata
const template = await ctx.createTemplate("template_path", schema, [], metadata /* optional */);

Installing Templates

Once we have the template, we can install it in a document by using the install method:

const document = await ctx.document("document_path");
if (!document.success) {
    // Handle error
}
const templateArrayToInstall = ["template_path"];
const newDoc = await document.data.install(templateArrayToInstall);

Uninstalling Templates

To uninstall a template from a document, we can use the uninstall method:

const document = await ctx.document("document_path");
if (!document.success) {
    // Handle error
}
const templateArrayToUninstall = ["template_path"];
const newDoc = await document.data.uninstall(templateArrayToUninstall);

📦 Assets

Upload new Assets

As a user, you can upload assets to your domain. When uploading an asset, you can specify the document path where the asset will be stored.

const ctxDocumentPath = "document/path";
const localFilePath = "file/path.jpg";
const asset = await ctx.createAsset(ctxDocumentPath, localFilePath, metadata /* optional */);

Update an Asset

You can update an existing asset by providing the document path and the local file path of the updated asset. It returns a document with a new version.

const localFilePath = "file/path.jpg";
const asset = await ctxDocument.data.updateAsset(localFilePath, metadata /* optional */);

🌐 Accessing Context Data

Every data on Context is publicly available, free, and forever for other developers to use locally through our public gateway:

https://rpc.ctx.xyz/domain/path/to/document

👨‍🔧 Error Handling

When calling a function, you can check if an error occurred by checking the error property in the returned object:

const document = await ctx.document("document_path");
if(document.success === false){
  console.error(document.error.error); // Error message
  console.error(document.error.message); // Detailed error message
  console.error(document.error.statusCode); // HTTP status code
}

✨ Create your first Domain

We are scheduled to launch on Mainnet in the coming weeks. If you are interested in becoming one of our early users, we encourage you to create your initial domain on our Beta using the WebApp.

For inquiries about creating a premium and verified domain, please contact us at support@ctx.xyz

NextExample Workflow

Last updated 1 month ago