Skip to content

Latest commit

 

History

History
444 lines (341 loc) · 22.2 KB

README.md

File metadata and controls

444 lines (341 loc) · 22.2 KB

cover

Arena-typed

Unofficial are.na API wrapper for TypeScript

Installation

npm install arena-typed

Quick start

To get started, create a new Arena instance and use its methods.

Note: Some actions require authentication. To obtain an access token:

  • Create a new application on are.na
  • Copy the value named Personal access token
  • Pass it to the Arena constructor ex. new Arena('your-access-token')
import Arena from 'arena-typed';

const arena = new Arena();

const channel = await arena.channels.get('arena-influences');
console.log(channel.title);

// or using promises
arena.channels.get('arena-influences').then((channel) => {
  console.log(channel.title);
});

Usage

The Arena class has four properties which are instances of subclasses with their own methods:

  • users
  • search
  • blocks
  • channels

Params

Some methods support pagination (optional), specified by pagination. Pass as an object like so: { page: 2, per: 15 }

Users

Method Returns Description
get(username: string) Promise<FollowingType> Get a specific user
channels(username: string) Promise<Channel[]> Get a list of the specified user's channels
followers(username: string) Promise<User[] Get a list of users following the specified user
following(username: string) Promise<User[]> Get a list of the specified user's followed channels and users

Examples

arena.users.get('testing-arena').then((users) => console.log('result', users));

arena.users.channels('testing-arena').then((channels) => console.log('result', channels));

arena.users.followers('testing-arena').then((followers) => console.log('result', followers));

arena.users.following('testing-arena').then((following) => console.log('result', following));

Search

Method Returns Description
all(query: string, pagination?: PaginationParams) Promise<SearchResponse> Perform a search
users(username: string) Promise<User[]> Search for users
channels(channel: string) Promise<Channel[] Search for channels
blocks(blocks: string) Promise<Block[]> Search for blocks

Examples

arena.search.all('testing').then((search) => console.log('result', search));

arena.search.users('testing-arena').then((search) => console.log('result', search));

arena.search.channels('arena-influences').then((search) => console.log('result', search));

arena.search.blocks('testing').then((search) => console.log('result', search));

Blocks

Method Returns Description
get(id: number) Promise<Block> Get a block
channels(id: number) Promise<Channel[] Get a list of channels the block is in
create(channel: string, data: BlockCreationData) Promise<Block> Create a new block in the specified channel
update(id: number, data: BlockUpdateData) Promise<void> Update a block that exists in the specified channel
delete(channel: string, id: number) Promise<void> Delete a block that exists in the specified channel

Examples

arena.blocks.channels(1234).then((channels) => console.log('channels', channels));

arena.blocks.create('new-channel-name', { source: 'new title' }).then((blocks) => console.log('result', blocks));

arena.blocks
  .update(123456, { title: 'updated title', description: 'updated description' })
  .catch((error) => console.log(error.message));

arena.blocks.delete('channel-name', 12345).catch((error) => console.log(error.message));

Channels

Method Returns Description
get (channel: string, pagination?: PaginationParams) Promise<Channel> Get a channel
thumb(channel: string) Promise<Channel Get basic information about a channel
connections(channel: string, pagination?: PaginationParams) Promise<Connection> Get all the connections within a channel
contents(channel: string, pagination?: PaginationParams) Promise<(Channel | Block)[]> Get only the contents of a channel (ex. no collaborators)
create(data: ChannelCreationData) Promise<Channel> Create a channel
update(channel: string, data: ChannelCreationData) Promise<Channel> Update a channel
delete(channel: string) Promise<void> Delete a channel
createBlock(channel: string, data: BlockCreationData) Promise<Block> Create a block in the specified channel
collaborators(channel: string) Promise<User[]> Get all users that are part of the specified channel, excluding the owner
addCollaborators(channel: string, users: CollaboratorData) Promise<User[]> Add collaborators to the specified channel
removeCollaborators(channel: string, users: CollaboratorData) Promise<User[]> Delete specified collaborators from the specified channel. Note: On the official documentaion, this request is supposed to remove users that are not specified in users. However, it currently works the other way around

Examples

arena.channels.get('channel-name').then((channel) => console.log('channel', channel));

arena.channels.thumb('channel-name').then((channel) => console.log('channel', channel));

arena.channels.connections('channel-name', { per, 20, page: 2 }).then((channels) => console.log('channel', channels));

arena.channels.contents('channel-name', { per: 3 }).then((contents) => console.log('contents', contents));

arena.channels
  .create({ title: 'new channel name', status: 'public' })
  .then((channel) => console.log('result', channel));

arena.channels
  .update('current-channel-name', { title: 'updated channel name' })
  .then((channel) => console.log('result', channel));

arena.channels
  .delete('channel-name')
  .then(() => console.log('success'))
  .catch((error) => console.log(error.message));

arena.channels
  .createBlock('channel-name', { source: 'new title' })
  .then((channels) => console.log('result', channels));

arena.channels.collaborators('channel-name').then((users) => console.log('collaborators', users));

arena.channels
  .addCollaborators('channel-name', { ids: [12345] })
  .then((channels) => console.log('result', channels));

arena.channels
  .removeCollaborators('updated-channel-name', { ids: [12345] })
  .then((channels) => console.log('result', channels));

Types

Users

Property Type
id number
slug string
username string
first_name string
last_name string
avatar string
avatar_image AvatarImage | null
channel_count number
following_count number
profile_id number
follower_count number
class "User"
initials string
AvatarImage
Property Type
thumb string
display string
Following
Property Type
Following User[] | Channel[] | Block[]
UserResponse
Property Type
base_class "User"
channel_title string | null
class "User"
current_page number
length number
per number
total_pages number
FollowerResponse
Property Type
users User[]
base_class "User"
channel_title string | null
class "User"
current_page number
length number
per number
total_pages number
FollowingResponse
Property Type
following FollowingType
base_class "User"
channel_title string | null
class "User"
current_page number
length number
per number
total_pages number
UserChannelsResponse
Property Type
channels Channel[]
base_class "User"
channel_title string | null
class "User"
current_page number
length number
per number
total_pages number

Search

SearchResponse
Property Type
term string
users User[]
channels Channel[]
blocks Block[]
total_pages number
current_page number
per number
length number

Blocks

Block
Property Type
id number
title string | null
updated_at Date
created_at Date
state "Available" | "Failure" | "Procesed" | "Processing"
comment_count number
generated_title string
class "Image" | "Text" | "Link" | "Media" | "Attachment"
base_class "Block"
content string | null
content_html string | null
description string | null
description_html string | null
source null | { title?: string; url: string; provider: { name: string; url: string; } | null; }
image null | { content_type: string; display: { url: string }; filename: string; lage: { url: string }l original: { file_size: number; file_size_display: string; url: string; }; square: { url: string }; thumb: { url: string }; updated_at: Date; }
user User
connections? Channel[] | undefined
Connection
Property Type
length number
total_pages number
current_page number
per number
channel_title string | null
base_class "Channels"
class "Channel"
channels Channel[]
BlocksResponse
Property Type
length number
total_pages number
current_page number
per number
channel_title string | null
base_class "Block"
class "Text"
channels Channel[]
ChannelsResponse
Property Type
base_class "Block"
channel_title string | null
channels Channel[]
class "Image" | "Text" | "Link" | "Media" | "Attachment"
current_page number
length number
per number
total_pages number
BlockCreationData

Note: Either source or content is required, but not both.

Property Type
source string | undefined
content string | undefined
BlockUpdateData
Property Type
title? string | undefined
description? string | undefined
content? string | undefined

Channels

Contents
Property Type
contents Array<Block | Channel>
Channel
Property Type
id number
title string
created_at Date
updated_at Date
published boolean
open boolean
collaboration boolean
slug string
length number
kind string
status string
user_id number
class string
base_class string
user User
total_pages number
current_page number
per number
follower_count number
contents (Block | Channel)[]
collaborators User[]
BlockAttributes
Property Type
position number
selected boolean
connected_at Date
connected_by_user_id number
PaginationParams
Property Type
page? number
per? number
ChannelCreationData
Property Type
title string
status? 'public' | 'closed' | 'private'
CollaboratorData
Property Type
ids number[]
CollaboratorResponse
Property Type
channel_title string | null
current_page number
length number
per number
total_pages number
GetOrDeleteCollaboratorsResponse
Property Type
channel_title string | null
current_page number
length number
per number
total_pages number
users User[]
AddCollaboratorsResponse
Property Type
channel_title string | null
current_page number
length number
per number
total_pages number
collaborators User[]