react-outpost

⚛️ 📨 Outpost is a utility to help serve decentralized media using Arweave to audiences who are in possession of a particular cryptocurrency. This React SDK helps you to easily integrate and distribute content via Outpost to social token holders in your own applications.

Find out more about the motivation behind Outpost here.

Supports Android, iOS, Web and Expo. ✨

If you'd like more information about Outpost, or to host your own community, please drop into the Outpost Discord!

🚀 Getting Started

Using Yarn:

yarn add react-outpost

Using npm:

npm i -s react-outpost

✏️ Tutorial

To interface with Outpost, you must declare an <OutpostProvider/> at the root of your application, which expects a single function prop, onRequestSignMessage, which is used to safely validate the user's social token ownership. In this callback, you can use a variety of ways to sign a message, for example Ethers or WalletConnect.

import React, { useCallback, useState } from 'react';
import Outpost from 'react-outpost';

import signPersonalMessage from "...";

export default function App(): JSX.Element {
  const onRequestSignMessage = useCallback(async (address: string, signInToken: string) => {
    return signPersonalMessage([
      signInToken,
      address,
    ]);
  }, []);
  return (
    <Outpost onRequestSignMessage={onRequestSignMessage}>
      {/* TODO: awesome decentralized app */}
    </Outpost>
  );
}

Once you're done, it's simple to interact with Outpost using the exposed hooks. For example, you can list all Outpost communities:

import { useAllCommunities } from 'react-outpost';

const { loading, error, communities } = useAllCommunities();

Or authenticate with Outpost to access secure content:

import { useOutpost } from 'react-outpost';

const { requestAuthToken } = useOutpost();
const authToken = await requestAuthToken(`0xdeadbeef`);

And you can even upload an image using the useOutpost hook, which internally wraps the Outpost SDK:

import { useOutpost } from 'react-outpost';

const { uploadImage } = useOutpost();
await uploadImage({
  authToken,
  base64: `data:image/png;base64,aGVsbG8sd29ybGQ...`,
});

You can check out the complete example application using WalletConnect as a message signer in React Native here.

🦄 API

OutpostProvider

A React Context Provider used to define the signing mechanism for Outpost Auth Challenges.

Prop Types

| Name | Type | Default | Description | |--------------------|---------------------------------------|----------------------------------------|-----------------------------------------------------------------------| | baseUrl | string | https://outpost-api-v2.herokuapp.com | URL of the Outpost Server. | | requestAuthToken | (string address) => Promise<string> | Promise.reject() | Provides the ability to sign a message for a given Ethereum address |

useOutpost

A utility hook used to return the complete Outpost Client API to a React Component nested within the OutpostProvider.

type createClientResult = {
  readonly getAllCommunities: () => Promise<readonly Community[]>;
  readonly getPosts: (params: getPostsParams) => Promise<getPostsResult>;
  readonly getChallenge: (
    params: getChallengeParams
  ) => Promise<getChallengeResult>;
  readonly getAuthToken: (
    params: getAuthTokenParams
  ) => Promise<getAuthTokenResult>;
  readonly getPostPreview: (
    params: getPostPreviewParams
  ) => Promise<getPostPreviewResult>;
  readonly uploadImage: (
    params: uploadImageParams
  ) => Promise<uploadImageResult>;
  readonly uploadPost: (params: uploadPostParams) => Promise<uploadPostResult>;
  readonly uploadComment: (
    params: uploadCommentParams
  ) => Promise<uploadCommentResult>;
  readonly getPost: (params: getPostParams) => Promise<getPostResult>;
};

type OutpostContextValue = createClientResult & {
  readonly baseURL: string;
  readonly requestAuthToken: (address: string) => Promise<string>;
};

readonly useOutpost(): OutpostContextValue;

useAllCommunities

Returns a list of all currently registered Communitys on Outpost.

readonly useAllCommunities: () => useAllCommunitiesResult;

export type useAllCommunitiesResult = {
  readonly loading: boolean;
  readonly communities: readonly Community[];
  readonly error: null | Error;
};

usePosts

Returns a list of all Posts for a Community.

readonly getPosts: (params: usePostsParams) => usePostsResult;

export type usePostsParams = {
  readonly slug: string;
};

export type usePostsResult = {
  readonly posts: readonly Post[];
  readonly loading: boolean;
  readonly error: null | Error;
};

useTxIdToUri

A helper utility that converts an Arweave Transaction Id (txId) to a navigable URL, based upon the provided gateway.

readonly useTxIdToUri: () => useTxIdToUriResult;

export type useTxIdToUriResult = {
  readonly txIdToUri: (gateway: string, txId: string) => string;
};

✌️ License

MIT