{"id":20263540,"url":"https://github.com/fleekhq/space-sdk","last_synced_at":"2025-04-06T21:14:47.441Z","repository":{"id":45795285,"uuid":"316605620","full_name":"FleekHQ/space-sdk","owner":"FleekHQ","description":"The Space SDK is a JavaScript/Typescript library for building web and mobile applications leveraging Open Web and distributed protocols like IPFS, Textile, GunDB, and Ethereum.","archived":false,"fork":false,"pushed_at":"2021-05-26T21:54:52.000Z","size":6791,"stargazers_count":194,"open_issues_count":7,"forks_count":22,"subscribers_count":20,"default_branch":"master","last_synced_at":"2025-03-30T20:11:16.184Z","etag":null,"topics":["filecoin","gundb","ipfs","sdk","storage","textile"],"latest_commit_sha":null,"homepage":"https://fleekhq.github.io/space-sdk/docs/","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/FleekHQ.png","metadata":{"files":{"readme":"README.md","changelog":"changelogs/v0.0.1.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2020-11-27T21:43:43.000Z","updated_at":"2025-03-30T00:47:32.000Z","dependencies_parsed_at":"2022-07-17T01:16:12.841Z","dependency_job_id":null,"html_url":"https://github.com/FleekHQ/space-sdk","commit_stats":null,"previous_names":[],"tags_count":30,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/FleekHQ%2Fspace-sdk","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/FleekHQ%2Fspace-sdk/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/FleekHQ%2Fspace-sdk/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/FleekHQ%2Fspace-sdk/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/FleekHQ","download_url":"https://codeload.github.com/FleekHQ/space-sdk/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247550689,"owners_count":20956987,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["filecoin","gundb","ipfs","sdk","storage","textile"],"created_at":"2024-11-14T11:35:28.815Z","updated_at":"2025-04-06T21:14:47.416Z","avatar_url":"https://github.com/FleekHQ.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"![](https://fleek-team-bucket.storage.fleek.co/Blog%20Inline/sdk.png)\n\n# Space SDK\n[![Fleek](https://img.shields.io/badge/Made%20by-Fleek-blue)](https://fleek.co/)\n[![Dev Slack](https://img.shields.io/badge/Dev%20Slack-Channel-blue)](https://slack.fleek.co/)\n[![License](https://img.shields.io/badge/License-MIT-green)](https://github.com/FleekHQ/space-sdk/blob/master/LICENSE)\n\n\n Javascript/Typescript library for interacting with Space in web/browser  applications via an implementation of the Space API. Build websites or applications that can easily leverage Open Web protocols (IPFS, Textile, GunDB, Ethereum) to enable Web3-ready features like:\n\n - File and directory storage / retrieval in user-controlled, encrypted, and distributed storage.\n - Key-pair based identity management and challenge-based authentication.\n - Decentralized and secure key and bucket metadata storage.\n - Private and end-to-end encrypted, or public file sharing.\n\n The Space SDK is  a close friend of the [Space Daemon](https://github.com/FleekHQ/space-daemon/), its desktop-focused counterpart. \n\n **You can find the SDK's documentation here:**\n* [Space SDK Documentation](https://fleekhq.github.io/space-sdk/docs/)\n* [Entire Space SDK package breakdown](https://fleekhq.github.io/space-sdk/docs/sdk)\n\n\n\n### Default Implementations\nThe Space SDK is modular and protocol agnostic. You can use the APIs and interfaces as is, with Space's default implementations, or replace them with your own custom ones.\n|Feature   \t|Description  \t| Service/Protocol\n|-:\t|-\t|-\t|\n| Users \t|  Key-pair based identity creation, and challenge authentication.\t| Textile Users API\n| Storage \t|  File, directory, and bucket creation/listing.\t| IPFS / Textile \n| Metadata \t|  Secure Bucket/directory schema storage\t| GunDB\n| Sharing \t|  Private and public file sharing\t| Textile |\n\n----\n \n## Introduction\n`@spacehq/sdk` provides a suit of functionality to perform different action on Space.\n\n## Installation\nInstall the sdk using this npm command:\n```\nnpm install @spacehq/sdk\n```\n\n## Usage\nSpace SDK provides an interface perform the following actions:\n\n- Creating identities\n\n- Create files and directories\n\n- List files and directories\n\n- Creating buckets\n\n- Sharing buckets\n\nFull SDK Documentation with examples can be found [here](https://fleekhq.github.io/space-sdk/)\n\n### 1. Identities\nThis involves managing users and their identities.\n\n```typescript\nimport { Users } from '@spacehq/sdk';\n\nconst users = new Users({ endpoint: 'wss://dev.space.storage' });\n\n// createIdentity generate a random keypair identity\nconst identity = await users.createIdentity();\n\n// the new keypair can be used to authenticate a new user\n// `users.authenticate()` generates hub API session tokens for the keypair identity.\nconst user = await users.authenticate(identity);\n// `user` can be used with the storage class to provide identity.\n\n// user's identity can also be backed up with a special recovery phrase\nconst uuid = 'specify-uuid-representing-user-in-your-system';\nconst passphrase = 'specify-unique-pass-phrase-related-to-backup-type';\nconst backupType = VaultBackupType.Google;\nawait users.backupKeysByPassphrase(uuid, passphrase, backupType, user.identity);\n\n// backed up users identity can also be recovered later\nconst recoveredUser = await users.recoverKeysByPassphrase(uuid, passphrase, backupType);\n// `recoveredUser` has same authentication as `user` above.\n```\n\nCheck the [User's](https://fleekhq.github.io/space-sdk/docs/sdk.users) class for more examples of how to manage users\nwith the sdk. \n\n### 2. Storage\nThis involves operations to create and list files and directories in space storage.\n\n```typescript\nimport { UserStorage, AddItemsResultSummary } from '@spacehq/sdk';\n\nconst storage = new UserStorage(user);\nawait storage.createFolder({ bucket: 'personal', path: 'topFolder' });\nconst result = await storage.listDirectory({ bucket: 'personal', path: '' });\n// result contains `topFolder` items\n\n// upload a file\nconst uploadResponse = await spaceStorage.addItems({\n   bucket: 'personal',\n   files: [\n     {\n       path: 'file.txt',\n       content: '',\n     },\n     {\n       path: 'space.png',\n       content: '',\n     }\n   ],\n});\n// uploadresponse is an event listener\nuploadResponse.once('done', (data: AddItemsEventData) =\u003e {\n  const summary = data as AddItemsResultSummary;\n  // returns a summary of all files and their upload status\n});\n```\n\n### 3. Sharing\nThis includes operations to share your storage items with existing user (identities)  \n\n```typescript\nimport { UserStorage } from '@space/sdk';\n\nconst storage = new UserStorage(user);\n\n// you can share privately with existing users via their public key:\nawait storage.shareViaPublicKey({\n    publicKeys: [{\n      id: 'user@email.com', // or any identifier for the user\n      pk: 'user-pk-hex-or-multibase', // optional, omit if user doesn't exist yet, it would generate temp access key\n    }],\n    paths: [{\n        bucket: 'personal',\n        path: '/file/path/here'\n    }],\n});\n\n// or you could share the file publicly by generating a link. Generated link references\nawait spaceStorage.setFilePublicAccess({\n  bucket: 'personal',\n  path: '/file.txt',\n  allowAccess: true, // \u003c- set to false to revoke public access\n});\n```\n\n## Migrating from Space Daemon\nIf you are already familiar with the space daemon and its gRPC methods and would like to start using the space-sdk\nhere are some pointers on how those gRPC methods correspond to functionalities exposed by the space-sdk.\n\n### Key Pairs (GenerateKeyPair)\nIn the sdk the concept of Key Pairs is represented as an [`Identity`](https://fleekhq.github.io/space-sdk/docs/sdk.identity).\nTo create a new Identity similar to the `GenerateKeyPair` method, you would do:\n\n```typescript\nimport { Users, BrowserStorage } from '@spacehq/sdk';\n\nconst users = new Users({ endpoint: 'wss://auth-dev.space.storage' });\n\n// createIdentity generate a random keypair identity\nconst identity = await users.createIdentity();\n```\n`identity` represents a keypair and its primary key is accessible via `identity.public.toString()`.\n\n### Managing authenticated users\n\nIn space-daemon the generated keypair is stored in the operating systems keychain but in space-sdk you would\nneed to provide an [IdentityStorage](https://fleekhq.github.io/space-sdk/docs/sdk.identitystorage) to the `Users` class when initializing it.\nFor the browser environment there exists a [`BrowserStorage`](https://fleekhq.github.io/space-sdk/docs/sdk.browserstorage) implementation\nyou can use.\n\n```typescript\nimport { Users, BrowserStorage } from '@spacehq/sdk';\n\nconst users = await Users.withStorage(\n    new BrowserStorage(), \n    { endpoint: 'wss://auth-dev.space.storage' }\n);\n```\n\n`Users.withStorage` will load and authenticate all identities that exist inside the provided `IdentityStorage`.\nYou can access all authenticated users through the [`Users.list`](https://fleekhq.github.io/space-sdk/docs/sdk.users.list) method.\n\n```typescript\nconst spaceUsers = await users.list();\n```\n\nTo authenticate a new user identity and get a [SpaceUser](https://fleekhq.github.io/space-sdk/docs/sdk.spaceuser), \nyou can call the [`Users.authenticate`](https://fleekhq.github.io/space-sdk/docs/sdk.users.authenticate) method:\n\n```typescript\nconst spaceUser = await users.authenticate(identity);\n```\n\n`Users.authentication` would do two things:\n- Generate a [`SpaceUser`](https://fleekhq.github.io/space-sdk/docs/sdk.spaceuser). \n- Stores the new users information in the `IdentityStorage`, so subsequent initialization of `Users.withStorage()` would \n  have the users loaded.\n  \nNOTE: An existing space user can also be gotten from [`Users.recoverKeysByPassphrase`](https://fleekhq.github.io/space-sdk/docs/sdk.users.recoverkeysbypassphrase).  \n\nTo delete a user from users lists, you can delete the user by pass the `publicKey` of that user to [`Users.remove`](https://fleekhq.github.io/space-sdk/docs/sdk.users.remove).\n\n```typescript\nawait users.remove(spaceUser.identity.public.toString());\n```\n\n#### Managing current active user\nIf you have the concept of a current active user in your application that uses space-sdk. We recommend that you keep track\nof that users public key in your application and use it to filter the [list](https://fleekhq.github.io/space-sdk/docs/sdk.users.list) \nmethod's result to get the authenticated `SpaceUser` for that public key. \n\nOn logout, you can call the [remove](https://fleekhq.github.io/space-sdk/docs/sdk.users.remove) method to stop tracking the user.\n\n### GetAPISessionToken\nIn space daemon GetAPISessionToken returns the message:\n\n```\nmessage GetAPISessionTokensResponse {\n  string hubToken = 1;\n  string servicesToken = 2;\n}\n```\n\nIn order to get the `servicesToken` and `hubToken` for a particular user, you would need to authenticate that user identity:\n```typescript\nconst spaceUser = await users.authenticate(identity);\n```\nThe `spaceUser.token` value is the `servicesToken`, while the `spaceUser.storageAuth.token` is the `hubToken`.\n\nAlso, note that when an existing user is recovered via the [`Users.recoverKeysByPassphrase`](https://fleekhq.github.io/space-sdk/docs/sdk.users.recoverkeysbypassphrase) \nmethod, the `SpaceUser` returns is also authenticated and has the session tokens.\n\n### GetPublicKey\nIn space daemon `GetPublicKey` returned the id of the current keypair in keychain, but since space-sdk returns the `identity`\nobject. You can get the public key bytes for a particular identity through `identity.public.pubKey`.\n\nAlso, an authenticated [`SpaceUser`](https://fleekhq.github.io/space-sdk/docs/sdk.spaceuser) identity can be found in the `identity` field.\n\n### Storage Methods (createFolder, listDirectory, openFile, addItems)\nThe storage gRPC methods on space daemon can now be performed using the [`UserStorage`](https://fleekhq.github.io/space-sdk/docs/sdk.userstorage) class of the space-sdk.\n\n```typescript\nimport { UserStorage, AddItemsResultSummary } from '@spacehq/sdk';\n\nconst storage = new UserStorage(user);\nawait storage.createFolder({ bucket: 'personal', path: 'topFolder' });\nconst result = await storage.listDirectory({ path: '' });\n// result contains `topFolder` items\n\n// upload a file\nconst uploadResponse = await spaceStorage.addItems({\n   bucket: 'personal',\n   files: [\n     {\n       path: 'file.txt',\n       content: 'plain-text-value',\n     },\n     {\n       path: 'space.png',\n       content: '', // could also be a ReadableStream\u003cUint8Array\u003e or ArrayBuffer\n     }\n   ],\n});\n// uploadresponse is an event listener\nuploadResponse.once('done', (data: AddItemsEventData) =\u003e {\n  const summary = data as AddItemsResultSummary;\n  // returns a summary of all files and their upload status\n});\n\n// read content of an uploaded file\nconst fileResponse = await storage.openFile({ bucket: 'personal', path: '/file.txt'});\nconst fileContent = await fileResponse.consumeStream();\n// new TextDecoder('utf8').decode(actualTxtContent) == 'plain-text-value'\n```\n\n\n## Contributing\n\nAll contributions are welcome. Before getting started, kindly take some time to review our [contributing guidelines](./CONTRIBUTING.md) \nand [code of conduct](./CODE_OF_CONDUCT.md).\n\n## LICENSE\n[MIT](./LICENSE)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ffleekhq%2Fspace-sdk","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ffleekhq%2Fspace-sdk","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ffleekhq%2Fspace-sdk/lists"}