@oddjs/odd

<!DOCTYPE html><html class="default" lang="en"><head><meta charSet="utf-8"/><meta http-equiv="x-ua-compatible" content="IE=edge"/><title>ODD SDK</title><meta name="description" content="Documentation for ODD SDK"/><meta name="viewport" content="width=device-width, initial-scale=1"/><link rel="stylesheet" href="assets/style.css"/><link rel="stylesheet" href="assets/highlight.css"/><script async src="assets/search.js" id="search-script"></script></head><body><script>document.documentElement.dataset.theme = localStorage.getItem("tsd-theme") || "os"</script><header class="tsd-page-toolbar"> <div class="tsd-toolbar-contents container"> <div class="table-cell" id="tsd-search" data-base="."> <div class="field"><label for="tsd-search-field" class="tsd-widget tsd-toolbar-icon search no-caption"><svg width="16" height="16" viewBox="0 0 16 16" fill="none"><path d="M15.7824 13.833L12.6666 10.7177C12.5259 10.5771 12.3353 10.499 12.1353 10.499H11.6259C12.4884 9.39596 13.001 8.00859 13.001 6.49937C13.001 2.90909 10.0914 0 6.50048 0C2.90959 0 0 2.90909 0 6.49937C0 10.0896 2.90959 12.9987 6.50048 12.9987C8.00996 12.9987 9.39756 12.4863 10.5008 11.6239V12.1332C10.5008 12.3332 10.5789 12.5238 10.7195 12.6644L13.8354 15.7797C14.1292 16.0734 14.6042 16.0734 14.8948 15.7797L15.7793 14.8954C16.0731 14.6017 16.0731 14.1267 15.7824 13.833ZM6.50048 10.499C4.29094 10.499 2.50018 8.71165 2.50018 6.49937C2.50018 4.29021 4.28781 2.49976 6.50048 2.49976C8.71001 2.49976 10.5008 4.28708 10.5008 6.49937C10.5008 8.70852 8.71314 10.499 6.50048 10.499Z" fill="var(--color-text)"></path></svg></label><input type="text" id="tsd-search-field" aria-label="Search"/></div> <div class="field"> <div id="tsd-toolbar-links"></div></div> <ul class="results"> <li class="state loading">Preparing search index...</li> <li class="state failure">The search index is not available</li></ul><a href="index.html" class="title">ODD SDK</a></div> <div class="table-cell" id="tsd-widgets"><a href="#" class="tsd-widget tsd-toolbar-icon menu no-caption" data-toggle="menu" aria-label="Menu"><svg width="16" height="16" viewBox="0 0 16 16" fill="none"><rect x="1" y="3" width="14" height="2" fill="var(--color-text)"></rect><rect x="1" y="7" width="14" height="2" fill="var(--color-text)"></rect><rect x="1" y="11" width="14" height="2" fill="var(--color-text)"></rect></svg></a></div></div></header> <div class="container container-main"> <div class="col-8 col-content"> <div class="tsd-page-title"> <h2>ODD SDK</h2></div> <div class="tsd-panel tsd-typography"> <a href="#odd-sdk" id="odd-sdk" style="color: inherit; text-decoration: none;"> <h1>ODD SDK</h1> </a> <a href="https://www.npmjs.com/package/@oddjs/odd"><img src="https://img.shields.io/npm/v/@oddjs/odd" alt="NPM"></a> <a href="https://github.com/oddsdk/ts-odd/blob/main/LICENSE"><img src="https://img.shields.io/badge/License-Apache%202.0-blue.svg" alt="License"></a> <a href="https://fission.codes"><img src="https://img.shields.io/badge/%E2%8C%98-Built_by_FISSION-purple.svg" alt="Built by FISSION"></a> <a href="https://discord.gg/zAQBDEq"><img src="https://img.shields.io/discord/478735028319158273.svg" alt="Discord"></a> <a href="https://talk.fission.codes"><img src="https://img.shields.io/discourse/https/talk.fission.codes/topics" alt="Discourse"></a> The ODD SDK empowers developers to build fully distributed web applications without needing a complex back-end. The SDK provides: <ul> <li>User accounts via the browser's <a href="https://developer.mozilla.org/en-US/docs/Web/API/Web_Crypto_API">Web Crypto API</a> or by using a blockchain wallet as a <a href="https://github.com/oddsdk/odd-walletauth">ODD plugin</a>.</li> <li>Authorization using <a href="https://ucan.xyz/">UCAN</a>.</li> <li>Encrypted file storage using <a href="https://docs.odd.dev/file-system-wnfs">WNFS</a> backed by <a href="https://ipld.io/">IPLD</a>.</li> <li>Key management using websockets and a two-factor auth-like flow.</li> </ul> ODD applications work offline and store data encrypted for the user by leveraging the power of the web platform. You can read more about the ODD SDK in Fission's <a href="https://docs.odd.dev">ODD SDK Guide</a>. There's also an API reference which can be found at <a href="https://api.odd.dev">api.odd.dev</a> <a href="#installation" id="installation" style="color: inherit; text-decoration: none;"> <h1>Installation</h1> </a> The <code>ts-odd</code> package is published on yarn, pnpm and npm as <code>@oddjs/odd</code>: <a href="#npm" id="npm" style="color: inherit; text-decoration: none;"> <h3>npm</h3> </a> <pre><code class="language-bash">npm install @oddjs/odd </code></pre> <a href="#pnpm" id="pnpm" style="color: inherit; text-decoration: none;"> <h3>pnpm</h3> </a> <pre><code class="language-bash">pnpm install @oddjs/odd </code></pre> <a href="#yarn" id="yarn" style="color: inherit; text-decoration: none;"> <h3>yarn</h3> </a> <pre><code class="language-bash">yarn add @oddjs/odd </code></pre> <a href="#getting-started" id="getting-started" style="color: inherit; text-decoration: none;"> <h1>Getting started</h1> </a> <pre><code class="language-ts">// ESM import * as odd from "@oddjs/odd" // Browser/UMD build const odd = globalThis.oddjs </code></pre> <a href="#creating-a-program" id="creating-a-program" style="color: inherit; text-decoration: none;"> <h2>Creating a Program</h2> </a> An ODD program is an assembly of components that make up a distributed web application. Several of the components can be customized. Let's stick with the default components for now, which means we'll be using the Web Crypto API. <pre><code class="language-ts">const program = await odd.program({ // Can also be a string, used as an identifier for caches. // If you're developing multiple apps on the same localhost port, // make sure these differ. namespace: { creator: "Nullsoft", name: "Winamp" } }).catch(error => { switch (error) { case odd.ProgramError.InsecureContext: // The ODD SDK requires HTTPS break; case odd.ProgramError.UnsupportedBrowser: break; } }) </code></pre> <code>odd.program</code> returns a <code>Program</code> object, which can create a new user session or reuse an existing session. There are two ways to create a user session, either by using an authentication strategy or by requesting access from another app through the "capabilities" system. Let's start with the default authentication strategy. <pre><code class="language-ts">let session // Do we have an existing session? if (program.session) { session = program.session // If not, let's authenticate. // (a) new user, register a new Fission account } else if (userChoseToRegister) { const { success } = await program.auth.register({ username: "llama" }) session = success ? program.auth.session() : null // (b) existing user, link a new device } else { // On device with existing session: const producer = await program.auth.accountProducer(program.session.username) producer.on("challenge", challenge => { // Either show `challenge.pin` or have the user input a PIN and see if they're equal. if (userInput === challenge.pin) challenge.confirmPin() else challenge.rejectPin() }) producer.on("link", ({ approved }) => { if (approved) console.log("Link device successfully") }) // On device without session: // Somehow you'll need to get ahold of the username. // Few ideas: URL query param, QR code, manual input. const consumer = await program.auth.accountConsumer(username) consumer.on("challenge", ({ pin }) => { showPinOnUI(pin) }) consumer.on("link", async ({ approved, username }) => { if (approved) { console.log(`Successfully authenticated as ${username}`) session = await program.auth.session() } }) } </code></pre> Alternatively you can use the "capabilities" system when you want partial access to a file system. At the moment of writing, capabilities are only supported through the "Fission auth lobby", which is an ODD app that uses the auth strategy shown above. This Fission auth lobby flow works as follows: <ol> <li>You get redirected to the Fission lobby from your app.</li> <li>Here you create an account like in the normal auth strategy flow shown above.</li> <li>The lobby shows what your app wants to access in your file system.</li> <li>You approve or deny these permissions and get redirected back to your app.</li> <li>Your app collects the encrypted information (UCANs & file system secrets).</li> <li>Your app can create a user session.</li> </ol> <pre><code class="language-ts">// We define a `Permissions` object, // this represents what permissions to ask the user. const permissions = { // Ask permission to write to and read from the directory: // private/Apps/Nullsoft/Winamp app: { creator: "Nullsoft", name: "Winamp" } } // We need to pass this object to our program const program = await odd.program({ namespace: { creator: "Nullsoft", name: "Winamp" }, permissions }) // (a) Whenever you are ready to redirect to the lobby, call this: program.capabilities.request() // (b) When you get redirected back and your program is ready, // you will have access to your user session. session = program.session </code></pre> Once you have your <code>Session</code>, you have access to your file system 🎉 <pre><code class="language-ts">const fs = session.fs </code></pre> Notes: <ul> <li>You can use alternative authentication strategies, such as <a href="https://github.com/oddsdk/odd-walletauth">odd-walletauth</a>.</li> <li>You can remove all traces of the user using <code>await session.destroy()</code></li> <li>You can load the file system separately if you're using a web worker. This is done using the combination of <code>configuration.fileSystem.loadImmediately = false</code> and <code>program.fileSystem.load()</code></li> <li>You can recover a file system if you've downloaded a Recovery Kit by calling <code>program.fileSystem.recover({ newUsername, oldUsername, readKey })</code>. The <code>oldUsername</code> and <code>readKey</code> can be parsed from the uploaded Recovery Kit and the <code>newUsername</code> can be generated before calling the function. Please refer to <a href="https://github.com/oddsdk/odd-app-template/blob/5498e7062a4578028b8b55d2ac4c611bd5daab85/src/components/auth/recover/HasRecoveryKit.svelte#L49">this example</a> from Fission's ODD App Template. Additionally, if you would like to see how to generate a Recovery Kit, you can reference <a href="https://github.com/oddsdk/odd-app-template/blob/main/src/lib/account-settings.ts#L186">this example</a></li> </ul> <a href="#working-with-the-file-system" id="working-with-the-file-system" style="color: inherit; text-decoration: none;"> <h2>Working with the file system</h2> </a> The Webnative File System (WNFS) is a file system built on top of <a href="https://ipld.io/">IPLD</a>. It supports operations similar to your macOS, Windows, or Linux desktop file system. It consists of a public and private branch: The public branch is "live" and publicly accessible on the Internet. The private branch is encrypted so that only the owner can see the contents. Read more about it <a href="https://github.com/wnfs-wg">here</a>. <pre><code class="language-ts">const { Branch } = odd.path // List the user's private files await fs.ls( odd.path.directory(Branch.Private) ) // Create a sub directory and add some content const contentPath = odd.file( Branch.Private, "Sub Directory", "hello.txt" ) await fs.write( contentPath, new TextEncoder().encode("👋") // Uint8Array ) // Persist changes and announce them to your other devices await fs.publish() // Read the file const content = new TextDecoder().decode( await fs.read(contentPath) ) </code></pre> That's it, you have successfully created an ODD app! 🚀 <a href="#posix-interface" id="posix-interface" style="color: inherit; text-decoration: none;"> <h2>POSIX Interface</h2> </a> WNFS exposes a familiar POSIX-style interface: <ul> <li><code>exists</code>: check if a file or directory exists</li> <li><code>ls</code>: list a directory</li> <li><code>mkdir</code>: create a directory</li> <li><code>mv</code>: move a file or directory</li> <li><code>read</code>: read from a file</li> <li><code>rm</code>: remove a file or directory</li> <li><code>write</code>: write to a file</li> </ul> <a href="#versioning" id="versioning" style="color: inherit; text-decoration: none;"> <h2>Versioning</h2> </a> Each file and directory has a <code>history</code> property, which you can use to get an earlier version of that item. We use the <code>delta</code> variable as the order index. Primarily because the timestamps can be slightly out of sequence, due to device inconsistencies. <pre><code class="language-ts">const file = await fs.get(odd.path.file("private", "Blog Posts", "article.md")) file.history.list() // { delta: -1, timestamp: 1606236743 } // { delta: -2, timestamp: 1606236532 } // Get the previous version file.history.back() // Go back two versions const delta = -2 file.history.back(delta) // Get the first version (ie. delta -2) // by providing a timestamp file.history.prior(1606236743) </code></pre> <a href="#sharing-private-data" id="sharing-private-data" style="color: inherit; text-decoration: none;"> <h2>Sharing Private Data</h2> </a> <a href="https://docs.odd.dev/sharing-private-data">https://docs.odd.dev/sharing-private-data</a> <a href="#migration" id="migration" style="color: inherit; text-decoration: none;"> <h2>Migration</h2> </a> Some versions of the ODD SDK require apps to migrate their codebase to address breaking changes. Please see our <a href="https://docs.odd.dev/developers/odd/migration">migration guide</a> for help migrating your apps to the latest ODD SDK version. <a href="#debugging" id="debugging" style="color: inherit; text-decoration: none;"> <h2>Debugging</h2> </a> Debugging mode can be enable by setting <code>debug</code> to <code>true</code> in your configuration object that you pass to your <code>Program</code>. By default this will add your programs to the global context object (eg. <code>window</code>) under <code>globalThis.__odd.programs</code> (can be disabled, see API docs). <pre><code class="language-ts">const appInfo = { creator: "Nullsoft", name: "Winamp" } await odd.program({ namespace: appInfo, debug: true }) // Automatically exposed Program in debug mode const program = globalThis.__odd[ odd.namespace(appInfo) ] // namespace: "Nullsoft/Winamp" </code></pre> </div></div> <div class="col-4 col-menu menu-sticky-wrap menu-highlight"> <div class="tsd-navigation settings"> <details class="tsd-index-accordion"><summary class="tsd-accordion-summary"> <h3><svg width="20" height="20" viewBox="0 0 24 24" fill="none"><path d="M4.93896 8.531L12 15.591L19.061 8.531L16.939 6.409L12 11.349L7.06098 6.409L4.93896 8.531Z" fill="var(--color-text)"></path></svg> Settings</h3></summary> <div class="tsd-accordion-details"> <div class="tsd-filter-visibility"> <h4 class="uppercase">Member Visibility</h4><form> <ul id="tsd-filter-options"> <li class="tsd-filter-item"><label class="tsd-filter-input"><input type="checkbox" id="tsd-filter-protected" name="protected"/><svg width="32" height="32" viewBox="0 0 32 32" aria-hidden="true"><rect class="tsd-checkbox-background" width="30" height="30" x="1" y="1" rx="6" fill="none"></rect><path class="tsd-checkbox-checkmark" d="M8.35422 16.8214L13.2143 21.75L24.6458 10.25" stroke="none" stroke-width="3.5" stroke-linejoin="round" fill="none"></path></svg>Protected</label></li> <li class="tsd-filter-item"><label class="tsd-filter-input"><input type="checkbox" id="tsd-filter-private" name="private"/><svg width="32" height="32" viewBox="0 0 32 32" aria-hidden="true"><rect class="tsd-checkbox-background" width="30" height="30" x="1" y="1" rx="6" fill="none"></rect><path class="tsd-checkbox-checkmark" d="M8.35422 16.8214L13.2143 21.75L24.6458 10.25" stroke="none" stroke-width="3.5" stroke-linejoin="round" fill="none"></path></svg>Private</label></li> <li class="tsd-filter-item"><label class="tsd-filter-input"><input type="checkbox" id="tsd-filter-inherited" name="inherited" checked/><svg width="32" height="32" viewBox="0 0 32 32" aria-hidden="true"><rect class="tsd-checkbox-background" width="30" height="30" x="1" y="1" rx="6" fill="none"></rect><path class="tsd-checkbox-checkmark" d="M8.35422 16.8214L13.2143 21.75L24.6458 10.25" stroke="none" stroke-width="3.5" stroke-linejoin="round" fill="none"></path></svg>Inherited</label></li></ul></form></div> <div class="tsd-theme-toggle"> <h4 class="uppercase">Theme</h4><select id="theme"><option value="os">OS</option><option value="light">Light</option><option value="dark">Dark</option></select></div></div></details></div> <nav class="tsd-navigation primary"> <details class="tsd-index-accordion" open><summary class="tsd-accordion-summary"> <h3><svg width="20" height="20" viewBox="0 0 24 24" fill="none"><path d="M4.93896 8.531L12 15.591L19.061 8.531L16.939 6.409L12 11.349L7.06098 6.409L4.93896 8.531Z" fill="var(--color-text)"></path></svg> Modules</h3></summary> <div class="tsd-accordion-details"> <ul> <li class="current selected"><a href="modules.html">ODD SDK</a> <ul> <li class="tsd-kind-module"><a href="modules/_internal_.html"><internal></a></li> <li class="tsd-kind-namespace"><a href="modules/Auth.html">Auth</a></li> <li class="tsd-kind-namespace"><a href="modules/Capabilities.html">Capabilities</a></li> <li class="tsd-kind-namespace"><a href="modules/Crypto.html">Crypto</a></li> <li class="tsd-kind-namespace"><a href="modules/Depot.html">Depot</a></li> <li class="tsd-kind-namespace"><a href="modules/Manners.html">Manners</a></li> <li class="tsd-kind-namespace"><a href="modules/Reference.html">Reference</a></li> <li class="tsd-kind-namespace"><a href="modules/Storage.html">Storage</a></li> <li class="tsd-kind-namespace"><a href="modules/apps.html">apps</a></li> <li class="tsd-kind-namespace"><a href="modules/did.html">did</a></li> <li class="tsd-kind-namespace"><a href="modules/fission.html">fission</a></li> <li class="tsd-kind-namespace"><a href="modules/path.html">path</a></li> <li class="tsd-kind-namespace"><a href="modules/ucan.html">ucan</a></li></ul></li></ul></div></details></nav></div></div> <div class="container tsd-generator"> Generated using <a href="https://typedoc.org/" target="_blank">TypeDoc</a></div> <div class="overlay"></div><script src="assets/main.js"></script></body></html>