@pubpub/sdk

v1.1.0

Published

7 days ago

Official PubPub API client for Node.js.

Downloads

230

0High
0Medium
0Low

pubpub

pubpub api sdk client publishing

PubPub SDK

GitHub license

Official Node.js SDK for PubPub.

PubPub SDK

Installation

If you use the SDK in Node, you must use Node 18 or higher in order to support native FormData.

pnpm add @pubpub/sdk
# yarn add @pubpub/sdk
# npm install @pubpub/sdk

Usage

import { PubPub } from '@pubpub/sdk'

const communityUrl = 'https://demo.pubpub.org'

async function main() {
  const pubpub = await PubPub.createSDK({
    communityUrl,
    email: '...',
    password: '...',
  })

  const pubs = await pubpub.pub.getMany()

  console.log(pubs)
}

main()

Replace https://demo.pubpub.org with your community URL, and replace … with your PubPUb login email address and password, respectively.

Limitations

The following actions are not permitted by the SDK, nor through the API in general:

Creating or deleting communities

Deleting a community is not permitted, due to the risk of accidental deletion of a community. Creating a community is not permitted, due to the potential for abuse (e.g., spam communities).

Creating, deleting, or modifying users

It is not possible to create, delete or modifying users, due to the risks involved.

Guides

Starting

import { PubPub } from '@pubpub/sdk'

const communityUrl = 'https://demo.pubpub.org'
const email = '...'
const password = '...'

const pubpub = await PubPub.createSDK({
  communityUrl,
  email,
  password,
})

Replace https://demo.pubpub.org with your community url, and replace … with your login email address and password, respectively.

Once your session is complete, you should logout:

await pubpub.logout()

Querying

Some models allow you to query them through the GET /api/<models> and GET /api/<models>/<id> endpoints on the API, and the PubPub.<model>.getMany and PubPub.<model>.get methods on the client.

These follow a standard pattern, and are documented here.

`get`/`GET /api/<models>/<id>`

The get methods allow you to get a single model by its id, OR by its slug (if it has one).

To get a single model by its id:

const pubById = await pubpub.pub.get({
  slugOrId: '00000000-0000-0000-0000-000000000000',
})

Replace 00000000-0000-0000-0000-000000000000 with the model’s id.

The slug of a Pub is the part of the URL after /pub. To get a single model by its slug:

// for https://demo.pubpub.org/pub/my-pub
const { body: myPub } = await pubpub.pub.get({
  slugOrId: 'my-pub',
})

Replace my-pub with your Pub’s slug.

`getMany`/`GET /api/<models>`

The getMany methods allow you to search for models. It returns an array of models.

You can filter models in the following ways

Pagination

By providing a limit and offset parameter, you can paginate the results.

Defaults

limit: 10
offset: 0

Example

const { body: firstTenCommunities } = await pubpub.community.getMany({
  limit: 10,
  offset: 0,
}) // this is the default

const { body: nextTenCommunities } = await pubpub.community.getMany({
  limit: 10,
  offset: 10,
})

Sorting

By providing orderBy and sortBy parameters, you can sort the results.

Options

The orderBy parameter can always be updatedAt or createdAt, and the sortBy parameter can always be ASC or DESC.

The orderBy parameters can also be some fiels of the model, depending on the model. Check the documentation of the specific method in the API section for more information.

Defaults

orderBy: createdAt
sortBy: DESC

Example

const { body: communitiesSortedByCreatedAt } = await pubpub.community.getMany({
  orderBy: 'createdAt',
  sortBy: 'DESC',
}) // this is the default

const { body: communitiesSortedByTitle } = await pubpub.community.getMany({
  query: {
    orderBy: 'title',
    sortBy: 'ASC',
  },
})

Includes

You can choose which associated models to include in the response by providing an includes parameter to your query.

By default, some models are always included. Currently this is not well documented here, check the documentation of the relevant API route to find this information.

[!NOTE] Specifying includes will override the default includes.

[!NOTE] The return type will not change based on the includes parameter. This means that even though you might have specified includes: ['pubAttributions'], the return type will have pubAttribubtions?: PubAttribution[] instead of pubAttributions: PubAttribution[].

Attributes

Maybe you don't need all the attributes of a model, and you want to save some bandwidth. You can do this by providing an attributes parameter to your query. This parameter is an array of attributes you want to include in the response.

[!NOTE] Specifying attributes will not change the return type. This means that even though you might have specified attributes: ['title'], the return type will still have description?: string instead of description: string.

Default

By default, all attributes are included.

Example

const { body: communitiesWithOnlyTitleAndCreatedAt } =
  await pubpub.community.getMany({
    query: {
      attributes: ['title', 'createdAt'],
    },
  })

console.log(communitiesWithOnlyTitleAndCreatedAt[0].title) // this works
console.log(communitiesWithOnlyTitleAndCreatedAt[0].description) // undefined

Filter

The most powerful way to query models is by providing a filter parameter to your query. This parameter is an object that allows you to filter the results based on the attributes of the model.

You can also provide filters as query parameters. E.g. instead of doing

const { body: pubs } = await pubpub.pub.getMany({
  query: {
    filter: {
      title: 'My pub',
    },
  },
})

Almost any attribute of a model can be used to filter the results. Check the documentation of the relevant API route to find this information.

The filters follow a standard patter.

Equality

By just defining the attribute you want to filter on, you can filter on equality.

{
    filter: {
        title: 'My community',
    }
}

will return all communities with the exact title (case-sensitive) 'My community'.

OR

You can provide an array of filters to filter on multiple values.

{
    filter: {
        title: ['My community', 'My other community'],
    }
}

will return all communities with the exact title (case-sensitive) 'My community' or 'My other community'.

AND

You can provide an object of filters to filter on multiple attributes.

{
    filter: {
        title: 'My community',
        description: 'This is my community',
    }
}

You can also do AND filters for the same property, by nesting arrays.

{
  filter: {
    title: [
      [
        {
          contains: 'My',
        },
        {
          contains: 'community',
        },
      ],
    ]
  }
}

This will return all communities with a title that contains both 'My' and 'community'. The contains filter for string values is documented below.

At the moment, you cannot easily do OR filters for multiple properties, please make multiple requests instead. If you find yourself needing this, please open an issue!

Existence

You can filter on whether an attribute exists or not by providing true or false as the value.

const attributionsWithUser = await pubpub.pubAttribution.getMany({
  query: {
    userId: true,
  },
})

String properties

If the property you are filtering on is a string, you can use the following filters.

string

If you provide a string, or { exact: string }, it will filter on equality.

const pubsCalledMyPub = await pubpub.pub.getMany({
  query: {
    title: 'My pub',
  },
})

boolean

If you provide a boolean, it will filter on existence.

const { body: pubsWithoutDownloads } = await pubpub.pub.getMany({
  query: {
    downloads: false,
  },
})

{ contains: string }

If you provide an object with a contains property, it will filter on whether the string contains the provided string.

This is case-insensitive.

const { body: pubsContainingPub } = await pubpub.pub.getMany({
  query: {
    title: {
      contains: 'pub',
    },
  },
})

{ contains: string; not: true }

If you provide an object with a contains property and a not property set to true, it will filter on whether the string does not contain the provided string.

const { body: pubsNotContainingPub } = await pubpub.pub.getMany({
  query: {
    title: {
      contains: 'pub',
      not: true,
    },
  },
})

There isn't a way to do { exact: string, not: true}, as this is almost always equivalent to { contains: string, not: true }.

If you find yourself needing this, please open an issue!

Full type

This is the full type of the filter parameter for string properties.

type StringFilter =
  | string
  | boolean
  | string[]
  | { exact: string }
  | { contains: string; not?: true | undefined }
  | (
      | string
      | { exact: string }
      | { contains: string; not?: true | undefined }
    )[]
  | (
      | string
      | boolean
      | { exact: string }
      | { contains: string; not?: true | undefined }
      | (
          | string
          | { exact: string }
          | { contains: string; not?: true | undefined }
        )[]
    )[]
  | undefined

Enum filters

For attributes that are enums, you can filter on the enum values. You cannot do contains queries.

const issues = await pubpub.collection.getMany({
  query: {
    kind: 'issue',
  },
})

You can of course also do OR filters.

const { body: issuesAndBooks } = await pubpub.collection.getMany({
  query: {
    kind: ['issue', 'book'],
  },
})

While you can technically do AND filters, this is not very useful, as the attribute can only have one value.

`id` filters

If the property is id or ends with Id (e.g. communityId), you can only provide a full UUID, an array of full UUIDs, or a boolean.

const { body: pub } = await pubpub.pub.get({
  id: '00000000-0000-0000-0000-000000000000',
})

`number` or `Date` filters

If the property is a number or a Date, you can use the following filters.

####### number | Date

If you provide a number, it will filter on equality.

const pubsCreatedAtAnExactDate = await pubpub.pub.getMany({
  query: {
    createdAt: new Date('2021-01-01'),
  },
})

{ gt: number | Date, lt: number | Date, eq: number | Date, gte: number | Date, lte: number | Date, ne: number | Date }

If you provide an object with any of the above properties, it will filter on the corresponding comparison.

const { body: pubsCreatedAfter2020 } = await pubpub.pub.getMany({
  query: {
    createdAt: {
      gt: new Date('2020-01-01'),
    },
  },
})

You can combine these as with other filters.

const { body: pubsCreatedBetween2020And2021 } = await pubpub.pub.getMany({
  query: {
    createdAt: {
      gt: new Date('2020-01-01'),
      lt: new Date('2021-01-01'),
    },
  },
})

const { body: pubsCreatedBefore2020OrAfter2021 } = await pubpub.pub.getMany({
  query: {
    createdAt: [
      {
        lt: new Date('2020-01-01'),
      },
      {
        gt: new Date('2021-01-01'),
      },
    ],
  },
})

Full types

type NumberFilter =
  | boolean
  | number
  | {
      eq?: number | undefined
      gt?: number | undefined
      gte?: number | undefined
      lt?: number | undefined
      lte?: number | undefined
      ne?: number | undefined
    }
  | (
      | number
      | {
          eq?: number | undefined
          gt?: number | undefined
          gte?: number | undefined
          lt?: number | undefined
          lte?: number | undefined
          ne?: number | undefined
        }
    )[]
  | (
      | boolean
      | number
      | {
          eq?: number | undefined
          gt?: number | undefined
          gte?: number | undefined
          lt?: number | undefined
          lte?: number | undefined
          ne?: number | undefined
        }
      | (
          | number
          | {
              eq?: number | undefined
              gt?: number | undefined
              gte?: number | undefined
              lt?: number | undefined
              lte?: number | undefined
              ne?: number | undefined
            }
        )[]
    )[]
  | undefined

For Dates, you can either input a Date object, or an ISO formatted string. It does not really matter, as it implicitly Date.toISOString() gets called on the value.

type Date =
  | boolean
  | string
  | Date
  | {
      eq?: Date | string | undefined
      gt?: Date | string | undefined
      gte?: Date | string | undefined
      lt?: Date | string | undefined
      lte?: Date | string | undefined
      ne?: Date | string | undefined
    }
  | (
      | string
      | Date
      | {
          eq?: Date | string | undefined
          gt?: Date | string | undefined
          gte?: Date | string | undefined
          lt?: Date | string | undefined
          lte?: Date | string | undefined
          ne?: Date | string | undefined
        }
    )[]
  | (
      | boolean
      | string
      | Date
      | {
          eq?: Date | string | undefined
          gt?: Date | string | undefined
          gte?: Date | string | undefined
          lt?: Date | string | undefined
          lte?: Date | string | undefined
          ne?: Date | string | undefined
        }
      | (
          | string
          | Date
          | {
              eq?: Date | string | undefined
              gt?: Date | string | undefined
              gte?: Date | string | undefined
              lt?: Date | string | undefined
              lte?: Date | string | undefined
              ne?: Date | string | undefined
            }
        )[]
    )[]
  | undefined

API

`pubpub.auth`

Methods for dealing with authentication

`pubpub.auth.login`

POST /api/login

login: (input, rest?) =>
  Promise<
    | { status: 201; body: 'success'; headers: Headers }
    | { status: 500; body: string; headers: Headers }
    | { status: 401; body: 'Login attempt failed'; headers: Headers }
  >

Access

You need to be logged in and have access to this resource.

Route Documentation

https://pubpub.org/apiDocs#/paths/api-login/post

Parameters

input

{
  email: string
  password: string
}

rest?

{
  cache: RequestCache
  extraHeaders: Record<string, undefined | string>
}

Returns

Promise<
  | {
      status: 201
      body: 'success'
      headers: Headers
    }
  | {
      status: 500
      body: string
      headers: Headers
    }
  | {
      status: 401
      body: 'Login attempt failed'
      headers: Headers
    }
>

`pubpub.auth.logout`

GET /api/logout

Logout and clear authentication cookie

logout: (input?) => Promise<{ status: 200; body: 'success'; headers: Headers }>

Access

You need to be logged in and have access to this resource.

Route Documentation

https://pubpub.org/apiDocs#/paths/api-logout/get

Parameters

input?

{
  cache?: RequestCache | undefined
  extraHeaders?:
    | ({
        [x: string]: undefined
        [x: number]: undefined
        [x: symbol]: undefined
      } & Record<string, string | undefined>)
    | undefined
}

Returns

Promise<{
  status: 200
  body: 'success'
  headers: Headers
}>

`pubpub.collection`

`pubpub.collection.create`

POST /api/collections

Create a collection

create: (input, rest?) =>
  Promise<{
    status: 201
    body: {
      id: string
      communityId: string
      title: string
      avatar: string | null
      viewHash: string | null
      editHash: string | null
      scopeSummaryId: string | null
      slug: string
      isRestricted: boolean | null
      isPublic: boolean | null
      metadata: Record<string, any> | null
      kind: 'tag' | 'issue' | 'book' | 'conference' | null
      doi: string | null
      readNextPreviewSize: 'none' | 'minimal' | 'medium' | 'choose-best'
      layout: Layout
      layoutAllowsDuplicatePubs: boolean
      pageId: string | null
      crossrefDepositRecordId: string | null
      createdAt?: string | undefined
      updatedAt?: string | undefined
    }
    headers: Headers
  }>

Access

You need to be logged in and have access to this resource.

Route Documentation

https://pubpub.org/apiDocs#/paths/api-collections/post

Parameters

input

{
  doi: undefined | null | string
  isPublic: undefined | null | boolean
  isRestricted: undefined | null | boolean
  kind: 'tag' | 'issue' | 'book' | 'conference'
  pageId: undefined | null | string
  slug: undefined | string
  title: string
}

rest?

{
  cache: RequestCache
  extraHeaders: Record<string, undefined | string>
}

Returns

Promise<{
  status: 201
  body: {
    id: string
    communityId: string
    title: string
    avatar: string | null
    viewHash: string | null
    editHash: string | null
    scopeSummaryId: string | null
    slug: string
    isRestricted: boolean | null
    isPublic: boolean | null
    metadata: Record<string, any> | null
    kind: 'tag' | 'issue' | 'book' | 'conference' | null
    doi: string | null
    readNextPreviewSize: 'none' | 'minimal' | 'medium' | 'choose-best'
    layout: Layout
    layoutAllowsDuplicatePubs: boolean
    pageId: string | null
    crossrefDepositRecordId: string | null
    createdAt?: string | undefined
    updatedAt?: string | undefined
  }
  headers: Headers
}>

`pubpub.collection.doi`

`pubpub.collection.doi.deposit`

POST /api/collections/:collectionId/doi

Deposit metadata to create a DOI

deposit: (input) =>
  Promise<
    | {
        status: 200
        body: {
          type: 'element'
          name: string
          attributes?: Record<string, string> | undefined
          children?: any[] | undefined
        }
        headers: Headers
      }
    | { status: 400; body: { error: string }; headers: Headers }
  >

Access

You need to be logged in and have access to this resource.

Route Documentation

https://pubpub.org/apiDocs#/paths/api-collections-collectionId-doi/post

Parameters

input

{
  cache: RequestCache
  extraHeaders: Record<string, undefined | string>
  params: {
    collectionId: string
  }
}

Returns

Promise<
  | {
      status: 200
      body: {
        type: 'element'
        name: string
        attributes?: Record<string, string> | undefined
        children?: any[] | undefined
      }
      headers: Headers
    }
  | {
      status: 400
      body: {
        error: string
      }
      headers: Headers
    }
>

`pubpub.collection.doi.preview`

POST /api/collections/:collectionId/doi/preview

Preview a DOI deposit

preview: (input) =>
  Promise<
    | {
        status: 200
        body: {
          type: 'element'
          name: string
          attributes?: Record<string, string> | undefined
          children?: any[] | undefined
        }
        headers: Headers
      }
    | { status: 400; body: { error: string }; headers: Headers }
  >

Access

You need to be logged in and have access to this resource.

Route Documentation

https://pubpub.org/apiDocs#/paths/api-collections-collectionId-doi-preview/post

Parameters

input

{
  cache: RequestCache
  extraHeaders: Record<string, undefined | string>
  params: {
    collectionId: string
  }
}

Returns

Promise<
  | {
      status: 200
      body: {
        type: 'element'
        name: string
        attributes?: Record<string, string> | undefined
        children?: any[] | undefined
      }
      headers: Headers
    }
  | {
      status: 400
      body: {
        error: string
      }
      headers: Headers
    }
>

`pubpub.collection.get`

GET /api/collections/:slugOrId

Get a collection by it's id or slug

get: (input) =>
  Promise<{
    status: 200
    body: {
      id: string
      communityId: string
      title: string
      avatar: string | null
      viewHash: string | null
      editHash: string | null
      scopeSummaryId: string | null
      slug: string
      isRestricted: boolean | null
      isPublic: boolean | null
      metadata: Record<string, any> | null
      kind: 'tag' | 'issue' | 'book' | 'conference' | null
      doi: string | null
      readNextPreviewSize: 'none' | 'minimal' | 'medium' | 'choose-best'
      layout: Layout
      layoutAllowsDuplicatePubs: boolean
      pageId: string | null
      crossrefDepositRecordId: string | null
      createdAt?: string | undefined
      updatedAt?: string | undefined
      attributions?: Attribution[]
      collectionPubs?: CollectionPub[]
      members?: Member[]
      page?: Page
      community?: Community
    }
    headers: Headers
  }>

Access

You need to be logged in and have access to this resource.

Route Documentation

https://pubpub.org/apiDocs#/paths/api-collections-slugOrId/get

Parameters

input

{
  params: { slugOrId: string }
  cache?: RequestCache | undefined
  extraHeaders?:
    | ({
        [x: string]: undefined
        [x: number]: undefined
        [x: symbol]: undefined
      } & Record<string, string | undefined>)
    | undefined
  query?:
    | {
        include?:
          | (
              | 'community'
              | 'attributions'
              | 'collectionPubs'
              | 'members'
              | 'page'
            )[]
          | undefined
        attributes?:
          | (
              | 'id'
              | 'communityId'
              | 'title'
              | 'avatar'
              | 'viewHash'
              | 'editHash'
              | 'scopeSummaryId'
              | 'slug'
              | 'isRestricted'
              | 'isPublic'
              | 'metadata'
              | 'kind'
              | 'doi'
              | 'readNextPreviewSize'
              | 'layout'
              | 'layoutAllowsDuplicatePubs'
              | 'pageId'
              | 'crossrefDepositRecordId'
            )[]
          | undefined
      }
    | undefined
}

Returns

Promise<{
  status: 200
  body: {
    id: string
    communityId: string
    title: string
    avatar: string | null
    viewHash: string | null
    editHash: string | null
    scopeSummaryId: string | null
    slug: string
    isRestricted: boolean | null
    isPublic: boolean | null
    metadata: Record<string, any> | null
    kind: 'tag' | 'issue' | 'book' | 'conference' | null
    doi: string | null
    readNextPreviewSize: 'none' | 'minimal' | 'medium' | 'choose-best'
    layout: Layout
    layoutAllowsDuplicatePubs: boolean
    pageId: string | null
    crossrefDepositRecordId: string | null
    createdAt?: string | undefined
    updatedAt?: string | undefined
    attributions?: Attribution[]
    collectionPubs?: CollectionPub[]
    members?: Member[]
    page?: Page
    community?: Community
  }
  headers: Headers
}>

`pubpub.collection.getMany`

GET /api/collections

Get many collections

getMany: (input?) =>
  Promise<{
    status: 200
    body: {
      id: string
      communityId: string
      title: string
      avatar: string | null
      viewHash: string | null
      editHash: string | null
      scopeSummaryId: string | null
      slug: string
      isRestricted: boolean | null
      isPublic: boolean | null
      metadata: Record<string, any> | null
      kind: 'tag' | 'issue' | 'book' | 'conference' | null
      doi: string | null
      readNextPreviewSize: 'none' | 'minimal' | 'medium' | 'choose-best'
      layout: Layout
      layoutAllowsDuplicatePubs: boolean
      pageId: string | null
      crossrefDepositRecordId: string | null
      createdAt?: string | undefined
      updatedAt?: string | undefined
      attributions?: Attribution[]
      collectionPubs?: CollectionPub[]
      members?: Member[]
      page?: Page
      community?: Community
    }[]
    headers: Headers
  }>

Access

You need to be logged in and have access to this resource.

Route Documentation

https://pubpub.org/apiDocs#/paths/api-collections/get

Parameters

input?

{
  query:
    | ({
        limit?: number | undefined
        offset?: number | undefined
        sortBy?:
          | 'createdAt'
          | 'updatedAt'
          | 'title'
          | 'slug'
          | 'kind'
          | undefined
        orderBy?: 'ASC' | 'DESC' | undefined
        filter?:
          | {
              id?: string | boolean | string[] | undefined
              communityId?: string | boolean | string[] | undefined
              title?: StringFilter
              avatar?: StringFilter
              viewHash?: StringFilter
              editHash?: StringFilter
              scopeSummaryId?: string | boolean | string[] | undefined
              slug?: StringFilter
              isRestricted?: boolean | undefined
              isPublic?: boolean | undefined
              metadata?: { [x: string]: any } | undefined
              kind?:
                | 'tag'
                | 'issue'
                | 'book'
                | 'conference'
                | ('tag' | 'issue' | 'book' | 'conference' | null)[]
                | null
                | undefined
              doi?: StringFilter
              readNextPreviewSize?:
                | 'none'
                | 'minimal'
                | 'medium'
                | 'choose-best'
                | ('none' | 'minimal' | 'medium' | 'choose-best')[]
                | undefined
              layoutAllowsDuplicatePubs?: boolean | undefined
              pageId?: string | boolean | string[] | undefined
              crossrefDepositRecordId?: string | boolean | string[] | undefined
              createdAt?: DateFilter
              updatedAt?: DateFilter
            }
          | undefined
        include?:
          | (
              | 'community'
              | 'attributions'
              | 'collectionPubs'
              | 'members'
              | 'page'
            )[]
          | undefined
        attributes?:
          | (
              | 'id'
              | 'createdAt'
              | 'updatedAt'
              | 'communityId'
              | 'title'
              | 'avatar'
              | 'viewHash'
              | 'editHash'
              | 'scopeSummaryId'
              | 'slug'
              | 'isRestricted'
              | 'isPublic'
              | 'metadata'
              | 'kind'
              | 'doi'
              | 'readNextPreviewSize'
              | 'layout'
              | 'layoutAllowsDuplicatePubs'
              | 'pageId'
              | 'crossrefDepositRecordId'
            )[]
          | undefined
      } & {
        id?: string | boolean | string[] | undefined
        communityId?: string | boolean | string[] | undefined
        title?: StringFilter
        avatar?: StringFilter
        viewHash?: StringFilter
        editHash?: StringFilter
        scopeSummaryId?: string | boolean | string[] | undefined
        slug?: StringFilter
        isRestricted?: boolean | undefined
        isPublic?: boolean | undefined
        metadata?: { [x: string]: any } | undefined
        kind?:
          | 'tag'
          | 'issue'
          | 'book'
          | 'conference'
          | ('tag' | 'issue' | 'book' | 'conference' | null)[]
          | null
          | undefined
        doi?: StringFilter
        readNextPreviewSize?:
          | 'none'
          | 'minimal'
          | 'medium'
          | 'choose-best'
          | ('none' | 'minimal' | 'medium' | 'choose-best')[]
          | undefined
        layoutAllowsDuplicatePubs?: boolean | undefined
        pageId?: string | boolean | string[] | undefined
        crossrefDepositRecordId?: string | boolean | string[] | undefined
        createdAt?: DateFilter
        updatedAt?: DateFilter
      })
    | undefined
  cache?: RequestCache | undefined
  extraHeaders?:
    | ({
        [x: string]: undefined
        [x: number]: undefined
        [x: symbol]: undefined
      } & Record<string, string | undefined>)
    | undefined
}

Returns

Promise<{
  status: 200
  body: {
    id: string
    communityId: string
    title: string
    avatar: string | null
    viewHash: string | null
    editHash: string | null
    scopeSummaryId: string | null
    slug: string
    isRestricted: boolean | null
    isPublic: boolean | null
    metadata: Record<string, any> | null
    kind: 'tag' | 'issue' | 'book' | 'conference' | null
    doi: string | null
    readNextPreviewSize: 'none' | 'minimal' | 'medium' | 'choose-best'
    layout: Layout
    layoutAllowsDuplicatePubs: boolean
    pageId: string | null
    crossrefDepositRecordId: string | null
    createdAt?: string | undefined
    updatedAt?: string | undefined
    attributions?: Attribution[]
    collectionPubs?: CollectionPub[]
    members?: Member[]
    page?: Page
    community?: Community
  }[]
  headers: Headers
}>

`pubpub.collection.getResource`

GET /api/collections/:collectionId/resource

Get collection as a resource

getResource: (input) => Promise<{ status: 200; body: any; headers: Headers }>

Access

You need to be logged in and have access to this resource.

Route Documentation

https://pubpub.org/apiDocs#/paths/api-collections-collectionId-resource/get

Parameters

input

{
  cache: RequestCache
  extraHeaders: Record<string, undefined | string>
  params: {
    collectionId: string
  }
}

Returns

Promise<{
  status: 200
  body: any
  headers: Headers
}>

`pubpub.collection.remove`

DELETE /api/collections

Remove a collection

remove: (input, rest?) =>
  Promise<{ status: 200; body: string; headers: Headers }>

Access

You need to be logged in and have access to this resource.

Route Documentation

https://pubpub.org/apiDocs#/paths/api-collections/delete

Parameters

input

{
  id: string
}

rest?

{
  cache: RequestCache
  extraHeaders: Record<string, undefined | string>
}

Returns

Promise<{
  status: 200
  body: string
  headers: Headers
}>

`pubpub.collection.update`

PUT /api/collections

Update a collection

update: (input, rest?) =>
  Promise<{
    status: 200
    body: {
      communityId?: string | undefined
      title?: string | undefined
      slug?: string | undefined
      isRestricted?: boolean | null | undefined
      isPublic?: boolean | null | undefined
      doi?: string | null | undefined
      pageId?: string | null | undefined
      kind?: 'tag' | 'issue' | 'book' | 'conference' | undefined
    }
    headers: Headers
  }>

Access

You need to be logged in and have access to this resource.

Route Documentation

https://pubpub.org/apiDocs#/paths/api-collections/put

Parameters

input

{
  avatar: null | string
  doi: null | string
  id: string
  isPublic: null | boolean
  isRestricted: null | boolean
  layout: Layout
  layoutAllowsDuplicatePubs: boolean
  metadata: null | Record<string, any>
  pageId: null | string
  readNextPreviewSize: 'none' | 'minimal' | 'medium' | 'choose-best'
  slug: string
  title: string
}

rest?

{
  cache: RequestCache
  extraHeaders: Record<string, undefined | string>
}

Returns

Promise<{
  status: 200
  body: {
    communityId?: string | undefined
    title?: string | undefined
    slug?: string | undefined
    isRestricted?: boolean | null | undefined
    isPublic?: boolean | null | undefined
    doi?: string | null | undefined
    pageId?: string | null | undefined
    kind?: 'tag' | 'issue' | 'book' | 'conference' | undefined
  }
  headers: Headers
}>

`pubpub.collectionAttribution`

`pubpub.collectionAttribution.batchCreate`

POST /api/collectionAttributions/batch

Batch create collection attributions

batchCreate: (input, rest?) =>
  Promise<{
    status: 201
    body: {
      id: string
      collectionId: string
      title: string | null
      avatar: string | null
      name: string | null
      order: number
      userId: string | null
      orcid: string | null
      isAuthor: boolean | null
      roles: string[] | null
      affiliation: string | null
      createdAt?: string | undefined
      updatedAt?: string | undefined
    }[]
    headers: Headers
  }>

Access

You need to be logged in and have access to this resource.

Route Documentation

https://pubpub.org/apiDocs#/paths/api-collectionAttributions-batch/post

Parameters

input

{
  attributions?: Attribution[]
  collectionId: string
}

rest?

{
  cache: RequestCache
  extraHeaders: Record<string, undefined | string>
}

Returns

Promise<{
  status: 201
  body: {
    id: string
    collectionId: string
    title: string | null
    avatar: string | null
    name: string | null
    order: number
    userId: string | null
    orcid: string | null
    isAuthor: boolean | null
    roles: string[] | null
    affiliation: string | null
    createdAt?: string | undefined
    updatedAt?: string | undefined
  }[]
  headers: Headers
}>

`pubpub.collectionAttribution.create`

POST /api/collectionAttributions

Create a collection attribution

create: (input, rest?) =>
  Promise<{
    status: 201
    body: {
      id: string
      collectionId: string
      title: string | null
      avatar: string | null
      name: string | null
      order: number
      userId: string | null
      orcid: string | null
      isAuthor: boolean | null
      roles: string[] | null
      affiliation: string | null
      createdAt?: string | undefined
      updatedAt?: string | undefined
    }
    headers: Headers
  }>

Access

You need to be logged in and have access to this resource.

Route Documentation

https://pubpub.org/apiDocs#/paths/api-collectionAttributions/post

Parameters

input

{
  affiliation: null | string
  avatar: null | string
  collectionId: string
  createdAt: string
  isAuthor: null | boolean
  name: string
  orcid: null | string
  order: number
  roles: null | string[]
  title: null | string
  updatedAt: string
  userId: null | string
}

rest?

{
  cache: RequestCache
  extraHeaders: Record<string, undefined | string>
}

Returns

Promise<{
  status: 201
  body: {
    id: string
    collectionId: string
    title: string | null
    avatar: string | null
    name: string | null
    order: number
    userId: string | null
    orcid: string | null
    isAuthor: boolean | null
    roles: string[] | null
    affiliation: string | null
    createdAt?: string | undefined
    updatedAt?: string | undefined
  }
  headers: Headers
}>

`pubpub.collectionAttribution.get`

GET /api/collectionAttributions/:id

Get a collection attribution

get: (input) =>
  Promise<{
    status: 200
    body: {
      id: string
      collectionId: string
      title: string | null
      avatar: string | null
      name: string | null
      order: number
      userId: string | null
      orcid: string | null
      isAuthor: boolean | null
      roles: string[] | null
      affiliation: string | null
      createdAt?: string | undefined
      updatedAt?: string | undefined
      collection?: Collection
      user?: User
    }
    headers: Headers
  }>

Access

You need to be an admin of this community in order to access this resource.

Route Documentation

https://pubpub.org/apiDocs#/paths/api-collectionAttributions-id/get

Parameters

input

{
  params: { id: string }
  cache?: RequestCache | undefined
  extraHeaders?:
    | ({
        [x: string]: undefined
        [x: number]: undefined
        [x: symbol]: undefined
      } & Record<string, string | undefined>)
    | undefined
  query?:
    | {
        include?: ('collection' | 'user')[] | undefined
        attributes?:
          | (
              | 'id'
              | 'collectionId'
              | 'title'
              | 'avatar'
              | 'name'
              | 'order'
              | 'userId'
              | 'orcid'
              | 'isAuthor'
              | 'roles'
              | 'affiliation'
            )[]
          | undefined
      }
    | undefined
}

Returns

Promise<{
  status: 200
  body: {
    id: string
    collectionId: string
    title: string | null
    avatar: string | null
    name: string | null
    order: number
    userId: string | null
    orcid: string | null
    isAuthor: boolean | null
    roles: string[] | null
    affiliation: string | null
    createdAt?: string | undefined
    updatedAt?: string | undefined
    collection?: Collection
    user?: User
  }
  headers: Headers
}>

`pubpub.collectionAttribution.getMany`

GET /api/collectionAttributions

Get multiple collection attributions. You are limited to attributions in your community.

getMany: (input?) =>
  Promise<{
    status: 200
    body: {
      id: string
      collectionId: string
      title: string | null
      avatar: string | null
      name: string | null
      order: number
      userId: string | null
      orcid: string | null
      isAuthor: boolean | null
      roles: string[] | null
      affiliation: string | null
      createdAt?: string | undefined
      updatedAt?: string | undefined
      collection?: Collection
      user?: User
    }[]
    headers: Headers
  }>

Access

You need to be an admin of this community in order to access this resource.

Route Documentation

https://pubpub.org/apiDocs#/paths/api-collectionAttributions/get

Parameters

input?

{
  query:
    | ({
        limit?: number | undefined
        offset?: number | undefined
        sortBy?:
          | 'createdAt'
          | 'updatedAt'
          | 'name'
          | 'order'
          | 'affiliation'
          | undefined
        orderBy?: 'ASC' | 'DESC' | undefined
        filter?:
          | {
              id?: string | boolean | string[] | undefined
              collectionId?: string | boolean | string[] | undefined
              title?: StringFilter
              avatar?: StringFilter
              name?: StringFilter
              order?: NumberFilter
              userId?: string | boolean | string[] | undefined
              orcid?: StringFilter
              isAuthor?: boolean | undefined
              roles?:
                | ( StringFilter
                  )[]
                | undefined
              affiliation?: StringFilter
              createdAt?: DateFilter
              updatedAt?: DateFilter
            }
          | undefined
        include?: ('collection' | 'user')[] | undefined
        attributes?:
          | (
              | 'id'
              | 'createdAt'
              | 'updatedAt'
              | 'collectionId'
              | 'title'
              | 'avatar'
              | 'name'
              | 'order'
              | 'userId'
              | 'orcid'
              | 'isAuthor'
              | 'roles'
              | 'affiliation'
            )[]
          | undefined
      } & {
        id?: string | boolean | string[] | undefined
        collectionId?: string | boolean | string[] | undefined
        title?: StringFilter
        avatar?: StringFilter
        name?: StringFilter
        order?: NumberFilter
        userId?: string | boolean | string[] | undefined
        orcid?: StringFilter
        isAuthor?: boolean | undefined
        roles?:
          | ( StringFilter
            )[]
          | undefined
        affiliation?: StringFilter
        createdAt?: DateFilter
        updatedAt?: DateFilter
      })
    | undefined
  cache?: RequestCache | undefined
  extraHeaders?:
    | ({
        [x: string]: undefined
        [x: number]: undefined
        [x: symbol]: undefined
      } & Record<string, string | undefined>)
    | undefined
}

Returns

Promise<{
  status: 200
  body: {
    id: string
    collectionId: string
    title: string | null
    avatar: string | null
    name: string | null
    order: number
    userId: string | null
    orcid: string | null
    isAuthor: boolean | null
    roles: string[] | null
    affiliation: string | null
    createdAt?: string | undefined
    updatedAt?: string | undefined
    collection?: Collection
    user?: User
  }[]
  headers: Headers
}>

`pubpub.collectionAttribution.remove`

DELETE /api/collectionAttributions

Remove a collection attribution

remove: (input, rest?) =>
  Promise<{ status: 200; body: string; headers: Headers }>

Access

You need to be logged in and have access to this resource.

Route Documentation

https://pubpub.org/apiDocs#/paths/api-collectionAttributions/delete

Parameters

input

{
  collectionId: string
  id: string
}

rest?

{
  cache: RequestCache
  extraHeaders: Record<string, undefined | string>
}

Returns

Promise<{
  status: 200
  body: string
  headers: Headers
}>

`pubpub.collectionAttribution.update`

PUT /api/collectionAttributions

Update a collection attribution

update: (input, rest?) =>
  Promise<{
    status: 200
    body: {
      createdAt?: string | undefined
      updatedAt?: string | undefined
      title?: string | null | undefined
      avatar?: string | null | undefined
      name?: string | null | undefined
      order?: number | undefined
      userId?: string | null | undefined
      orcid?: string | null | undefined
      isAuthor?: boolean | null | undefined
      roles?: string[] | null | undefined
      affiliation?: string | null | undefined
    }
    headers: Headers
  }>

Access

You need to be logged in and have access to this resource.

Route Documentation

https://pubpub.org/apiDocs#/paths/api-collectionAttributions/put

Parameters

input

{
  affiliation: null | string
  avatar: null | string
  collectionId: string
  createdAt: string
  id: string
  isAuthor: null | boolean
  name: null | string
  orcid: null | string
  order: number
  roles: null | string[]
  title: null | string
  updatedAt: string
  userId: null | string
}

rest?

{
  cache: RequestCache
  extraHeaders: Record<string, undefined | string>
}

Returns

Promise<{
  status: 200
  body: {
    createdAt?: string | undefined
    updatedAt?: string | undefined
    title?: string | null | undefined
    avatar?: string | null | undefined
    name?: string | null | undefined
    order?: number | undefined
    userId?: string | null | undefined
    orcid?: string | null | undefined
    isAuthor?: boolean | null | undefined
    roles?: string[] | null | undefined
    affiliation?: string | null | undefined
  }
  headers: Headers
}>

`pubpub.collectionPub`

`pubpub.collectionPub.create`

POST /api/collectionPubs

Add a pub to a collection

create: (input, rest?) =>
  Promise<{
    status: 201
    body: {
      id: string
      pubId: string
      collectionId: string
      rank: string
      contextHint: string | null
      pubRank: string
      createdAt?: string | undefined
      updatedAt?: string | undefined
    }
    headers: Headers
  }>

Access

You need to be logged in and have access to this resource.

Route Documentation

https://pubpub.org/apiDocs#/paths/api-collectionPubs/post

Parameters

input

{
  collectionId: string
  moveToTop: boolean
  pubId: string
  rank: string
}

rest?

{
  cache: RequestCache
  extraHeaders: Record<string, undefined | string>
}

Returns

Promise<{
  status: 201
  body: {
    id: string
    pubId: string
    collectionId: string
    rank: string
    contextHint: string | null
    pubRank: string
    createdAt?: string | undefined
    updatedAt?: string | undefined
  }
  headers: Headers
}>

`pubpub.collectionPub.get`

GET /api/collectionPubs

Get the pubs associated with a collection

get: (input?) =>
  Promise<{
    status: 200
    body: {
      id: string
      communityId: string
      title: string
      description: string | null
      avatar: string | null
      viewHash: string | null
      editHash: string | null
      scopeSummaryId: string | null
      slug: string
      metadata: {
        mtg_id: string
        bibcode: string
        mtg_presentation_id: string
      } | null
      doi: string | null
      crossrefDepositRecordId: string | null
      htmlTitle: string | null
      htmlDescription: string | null
      customPublishedAt: string | null
      labels:
        | { id: string; title: string; color: string; publicApply: boolean }[]
        | null
      downloads: { createdAt: string; type: 'formatted'; url: string }[] | null
      reviewHash: string | null
      commentHash: string | null
      draftId: string
      createdAt?: string | undefined
      updatedAt?: string | undefined
    }[]
    headers: Headers
  }>

Access

You need to be logged in and have access to this resource.

Route Documentation

https://pubpub.org/apiDocs#/paths/api-collectionPubs/get

Parameters

input?

{
  query: {
    collectionId: string
    communityId: string
    pubId?: string | undefined
    limit?: number | undefined
    offset?: number | undefined
  }
  cache?: RequestCache | undefined
  extraHeaders?:
    | ({
        [x: string]: undefined
        [x: number]: undefined
        [x: symbol]: undefined
      } & Record<string, string | undefined>)
    | undefined
}

Returns

Promise<{
  status: 200
  body: {
    id: string
    communityId: string
    title: string
    description: string | null
    avatar: string | null
    viewHash: string | null
    editHash: string | null
    scopeSummaryId: string | null
    slug: string
    metadata: {
      mtg_id: string
      bibcode: string
      mtg_presentation_id: string
    } | null
    doi: string | null
    crossrefDepositRecordId: string | null
    htmlTitle: string | null
    htmlDescription: string | null
    customPublishedAt: string | null
    labels:
      | {
          id: string
          title: string
          color: string
          publicApply: boolean
        }[]
      | null
    downloads:
      | {
          createdAt: string
          type: 'formatted'
          url: string
        }[]
      | null
    reviewHash: string | null
    commentHash: string | null
    draftId: string
    createdAt?: string | undefined
    updatedAt?: string | undefined
  }[]
  headers: Headers
}>

`pubpub.collectionPub.remove`

DELETE /api/collectionPubs

Remove a pub from a collection

remove: (input, rest?) =>
  Promise<{ status: 200; body: string; headers: Headers }>

Access

You need to be logged in and have access to this resource.

Route Documentation

<https://pubpub.org/apiDocs#/path

Published

Vulnerabilities

Links

Maintainers

Keywords

Readme

PubPub SDK

Contents

Installation

Usage

Limitations

Creating or deleting communities

Creating, deleting, or modifying users

Guides

Starting

Querying

get/GET /api/<models>/<id>

getMany/GET /api/<models>

Pagination

Defaults

Example

Sorting

Options

Defaults

Example

Includes

Attributes

Default

Example

Filter

Equality

OR

AND

Existence

String properties

Enum filters

id filters

number or Date filters

API

pubpub.auth

pubpub.auth.login

Access

Route Documentation

Parameters

Returns

pubpub.auth.logout

Access

Route Documentation

Parameters

Returns

pubpub.collection

pubpub.collection.create

Access

Route Documentation

Parameters

Returns

pubpub.collection.doi

pubpub.collection.doi.deposit

Access

Route Documentation

Parameters

Returns

pubpub.collection.doi.preview

Access

Route Documentation

Parameters

Returns

pubpub.collection.get

Access

Route Documentation

Parameters

Returns

pubpub.collection.getMany

Access

Route Documentation

Parameters

Returns

pubpub.collection.getResource

Access

Route Documentation

`get`/`GET /api/<models>/<id>`

`getMany`/`GET /api/<models>`

`id` filters

`number` or `Date` filters

`pubpub.auth`

`pubpub.auth.login`

`pubpub.auth.logout`

`pubpub.collection`

`pubpub.collection.create`

`pubpub.collection.doi`

`pubpub.collection.doi.deposit`

`pubpub.collection.doi.preview`

`pubpub.collection.get`

`pubpub.collection.getMany`

`pubpub.collection.getResource`

`pubpub.collection.remove`

`pubpub.collection.update`

`pubpub.collectionAttribution`

`pubpub.collectionAttribution.batchCreate`

`pubpub.collectionAttribution.create`

`pubpub.collectionAttribution.get`

`pubpub.collectionAttribution.getMany`

`pubpub.collectionAttribution.remove`

`pubpub.collectionAttribution.update`