Skai SDK

Official TypeScript SDK for the Skai Protocol.

The Skai SDK is the reference implementation of the Skai Protocol. It provides everything needed to build clients and servers that communicate over Skainet.

This SDK is intentionally lightweight. It focuses on implementing the protocol, not adding unnecessary abstractions.

Table of Contents

• About
• Goals
• Features
• Installation
• Project Structure
• Concepts
• Architecture
• Client API
• Server API
• Protocol
• Examples
• Roadmap
• Contributing
• License

About

Skai is an experimental service-oriented protocol.

Instead of interacting with websites, applications communicate with services.

Example:

skai://chat.ski/send

The SDK handles creating protocol messages, sending them, parsing responses, and validating packets.

It does not implement the network itself.

That responsibility belongs to skai-node.

Goals

The SDK is designed with a few simple principles.

• Lightweight
• Easy to understand
• Fully typed
• Zero external dependencies (whenever possible)
• Protocol-first
• Runtime agnostic

The SDK should work in:

• Browsers
• Node.js
• Cloudflare Workers
• Bun
• Deno

Features

Current features:

• Request builder
• Response builder
• Protocol validation
• Request parser
• Response parser
• JSON serializer
• JSON deserializer
• Client API
• Server utilities

Planned features:

• Authentication helpers
• Streaming
• Binary serialization
• Compression
• Plugins

Installation

npm install skai-sdk

Project Structure

src/
│
├── client.ts
├── server.ts
├── protocol.ts
├── parser.ts
├── serializer.ts
├── types.ts
└── index.ts

client.ts

Contains the client implementation.

Responsible for:

• Sending requests
• Receiving responses

server.ts

Contains helper utilities used by Skai Nodes.

Responsible for:

• Parsing requests
• Creating responses

protocol.ts

Contains protocol validation.

Examples:

• Request validation
• Response validation
• Version checking

parser.ts

Converts JSON into protocol objects.

serializer.ts

Converts protocol objects into JSON.

types.ts

Contains every protocol interface.

index.ts

Exports the entire public API.

Concepts

Client

Applications communicate using a client.

Example:

const skai = new SkaiClient();

const response = await skai.call(
    "chat.ski",
    "send",
    {
        text: "Hello!"
    }
);

Server

Nodes receive requests using the server utilities.

const request = parseRequest(raw);

Request

Every request follows the protocol specification.

{
    "version":1,
    "host":"chat.ski",
    "action":"send",
    "body":{
        "text":"Hello"
    }
}

Response

Responses always return a status.

{
    "status":"ok",
    "body":{
        "message":"Sent"
    }
}

Architecture

Application

↓

Skai SDK

↓

Transport (HTTPS)

↓

Skai Node

The SDK never communicates directly with services.

It communicates with a Skai Node.

Public API

SkaiClient

Primary client class.

Methods:

call()

call(
    host,
    action,
    body
)

Creates a request.

Sends it.

Returns the parsed response.

parseRequest()

Parses a raw request.

Returns a typed object.

parseResponse()

Parses a raw response.

Returns a typed object.

serializeRequest()

Converts a request into JSON.

serializeResponse()

Converts a response into JSON.

validateRequest()

Validates request structure.

validateResponse()

Validates response structure.

Error Handling

Every parser throws an Error if the message is invalid.

Example:

try {

}
catch(err){

}

Applications are expected to catch parser errors.

Examples

Ping

await skai.call(
    "kernel.ski",
    "ping",
    {}
);

Chat

await skai.call(
    "chat.ski",
    "send",
    {
        text:"Hello!"
    }
);

File Read

await skai.call(
    "files.ski",
    "read",
    {
        path:"hello.txt"
    }
);

Roadmap

Version 0.1

• Basic protocol
• JSON transport
• Client
• Server

Version 0.2

• Authentication
• Better validation

Version 0.3

• Streaming

Version 1.0

Stable protocol.

Contributing

This project is currently experimental.

Contributions are welcome after Version 0.5.

License

GNU GPLv3