@pubpub/sdk v1.0.2
PubPub SDK
Official Node.js SDK for PubPub.
Contents
- Installation
- Usage
- Limitations
- Guides
- API
- Contributing
- TODO
- FAQ
- License
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/sdkUsage
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:10offset: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:createdAtsortBy: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
includeswill override the default includes.[!NOTE] The return type will not change based on the
includesparameter. This means that even though you might have specifiedincludes: ['pubAttributions'], the return type will havepubAttribubtions?: PubAttribution[]instead ofpubAttributions: 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
attributeswill not change the return type. This means that even though you might have specifiedattributes: ['title'], the return type will still havedescription?: stringinstead ofdescription: 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) // undefinedFilter
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 }
)[]
)[]
| undefinedEnum 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
}
)[]
)[]
| undefinedFor 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
}
)[]
)[]
| undefinedAPI
pubpub.auth
Methods for dealing with authentication
pubpub.auth.login
POST /api/login
Login and returns authentication cookie
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
isAuthor: boolean | null
roles: string[] | null
affiliation: string | null
orcid: string | null
userId: 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
isAuthor: boolean | null
roles: string[] | null
affiliation: string | null
orcid: string | null
userId: 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
isAuthor: boolean | null
roles: string[] | null
affiliation: string | null
orcid: string | null
userId: 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
isAuthor: boolean | null
roles: string[] | null
affiliation: string | null
orcid: string | null
userId: 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
isAuthor: boolean | null
roles: string[] | null
affiliation: string | null
orcid: string | null
userId: 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'
| 'isAuthor'
| 'roles'
| 'affiliation'
| 'orcid'
| 'userId'
)[]
| undefined
}
| undefined
}Returns
Promise<{
status: 200
body: {
id: string
collectionId: string
title: string | null
avatar: string | null
name: string | null
order: number
isAuthor: boolean | null
roles: string[] | null
affiliation: string | null
orcid: string | null
userId: 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
isAuthor: boolean | null
roles: string[] | null
affiliation: string | null
orcid: string | null
userId: 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
isAuthor?: boolean | undefined
roles?:
| ( StringFilter
)[]
| undefined
affiliation?: StringFilter
orcid?: StringFilter
userId?: string | boolean | string[] | undefined
createdAt?: DateFilter
updatedAt?: DateFilter
}
| undefined
include?: ('collection' | 'user')[] | undefined
attributes?:
| (
| 'id'
| 'createdAt'
| 'updatedAt'
| 'collectionId'
| 'title'
| 'avatar'
| 'name'
| 'order'
| 'isAuthor'
| 'roles'
| 'affiliation'
| 'orcid'
| 'userId'
)[]
| undefined
} & {
id?: string | boolean | string[] | undefined
collectionId?: string | boolean | string[] | undefined
title?: StringFilter
avatar?: StringFilter
name?: StringFilter
order?: NumberFilter
isAuthor?: boolean | undefined
roles?:
| ( StringFilter
)[]
| undefined
affiliation?: StringFilter
orcid?: StringFilter
userId?: 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
collectionId: string
title: string | null
avatar: string | null
name: string | null
order: number
isAuthor: boolean | null
roles: string[] | null
affiliation: string | null
orcid: string | null
userId: 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
isAuthor?: boolean | null | undefined
roles?: string[] | null | undefined
affiliation?: string | null | undefined
orcid?: string | null | undefined
userId?: 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
isAuthor?: boolean | null | undefined
roles?: string[] | null | undefined
affiliation?: string | null | undefined
orcid?: string | null | undefined
userId?: 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
}
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#/paths/api-collectionPubs/delete
Parameters
input
{
id: string
}rest?
{
cache: RequestCache
extraHeaders: Record<string, undefined | string>
}Returns
Promise<{
status: 200
body: string
headers: Headers
}>pubpub.collectionPub.update
PUT /api/collectionPubs
Change the pubs that are associated with a collection
update: (input, rest?) =>
Promise<{
status: 200
body: {
pubId?: string | undefined
collectionId?: string | undefined
rank?: string | undefined
contextHint?: string | null | undefined
pubRank?: 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/put
Parameters
input
{
collectionId: string
contextHint: null | string
id: string
pubId: string
pubRank: string
rank: string
}rest?
{
cache: RequestCache
extraHeaders: Record<string, undefined | string>
}Returns
Promise<{
status: 200
body: {
pubId?: string | undefined
collectionId?: string | undefined
rank?: string | undefined
contextHint?: string | null | undefined
pubRank?: string | undefined
}
headers: Headers
}>pubpub.community
pubpub.community.create
POST /api/communities
Create a community
create: (input, rest?) =>
Promise<{ status: 201; 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-communities/post
Parameters
input
{
accentColorDark: undefined | string
accentColorLight: undefined | string
description: undefined | null | string
headerLogo: undefined | null | string
heroLogo: undefined | null | string
heroTitle: undefined | null | string
subdomain: string
title: string
}rest?
{
cache: RequestCache
extraHeaders: Record<string, undefined | string>
}Returns
Promise<{
status: 201
body: string
headers: Headers
}>pubpub.community.get
GET /api/communities/:id
Get a community
get: (input) =>
Promise<{
status: 200
body: {
id: string
subdomain: string
domain: string | null
title: string
citeAs: string | null
publishAs: string | null
description: string | null
avatar: string | null
favicon: string | null
accentColorLight: string
accentColorDark: string
hideCreatePubButton: boolean | null
headerLogo: string | null
headerLinks:
| { title: string; url: string; external?: boolean | undefined }[]
| null
headerColorType: 'light' | 'dark' | 'custom' | null
useHeaderTextAccent: boolean | null
hideHero: boolean | null
hideHeaderLogo: boolean | null
heroLogo: string | null
heroBackgroundImage: string | null
heroBackgroundColor: string | null
heroTextColor: string | null
useHeaderGradient: boolean | null
heroImage: string | null
heroTitle: string | null
heroText: string | null
heroPrimaryButton: { title: string; url: string } | null
heroSecondaryButton: { title: string; url: string } | null
heroAlign: string | null
navigation:
| (
| { id: string; type: 'collection' | 'page' }
| { id: string; title: string; href: string }
| {
id: string
title: string
children: (
| { id: string; type: 'collection' | 'page' }
| { id: string; title: string; href: string }
)[]
}
)[]
| null
hideNav: boolean | null
navLinks:
| (
| { id: string; type: 'collection' | 'page' }
| { id: string; title: string; href: string }
| {
id: string
title: string
children: (
| { id: string; type: 'collection' | 'page' }
| { id: string; title: string; href: string }
)[]
}
)[]
| null
footerLinks:
| (
| { id: string; type: 'collection' | 'page' }
| { id: string; title: string; href: string }
| {
id: string
title: string
children: (
| { id: string; type: 'collection' | 'page' }
| { id: string; title: string; href: string }
)[]
}
)[]
| null
footerLogoLink: string | null
footerTitle: string | null
footerImage: string | null
website: string | null
facebook: string | null
twitter: string | null
email: string | null
issn: string | null
isFeatured: boolean | null
viewHash: string | null
editHash: string | null
premiumLicenseFlag: boolean | null
defaultPubCollections: string[] | null
spamTagId: string | null
organizationId: string | null
scopeSummaryId: string | null
accentTextColor: 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-communities-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
}Returns
Promise<{
status: 200
body: {
id: string
subdomain: string
domain: string | null
title: string
citeAs: string | null
publishAs: string | null
description: string | null
avatar: string | null
favicon: string | null
accentColorLight: string
accentColorDark: string
hideCreatePubButton: boolean | null
headerLogo: string | null
headerLinks:
| {
title: string
url: string
external?: boolean | undefined
}[]
| null
headerColorType: 'light' | 'dark' | 'custom' | null
useHeaderTextAccent: boolean | null
hideHero: boolean | null
hideHeaderLogo: boolean | null
heroLogo: string | null
heroBackgroundImage: string | null
heroBackgroundColor: string | null
heroTextColor: string | null
useHeaderGradient: boolean | null
heroImage: string | null
heroTitle: string | null
heroText: string | null
heroPrimaryButton: {
title: string
url: string
} | null
heroSecondaryButton: {
title: string
url: string
} | null
heroAlign: string | null
navigation:
| (
| {
id: string
type: 'collection' | 'page'
}
| {
id: string
title: string
href: string
}
| {
id: string
title: string
children: (
| {
id: string
type: 'collection' | 'page'
}
| {
id: string
title: string
href: string
}
)[]
}
)[]
| null
hideNav: boolean | null
navLinks:
| (
| {
id: string
type: 'collection' | 'page'
}
| {
id: string
title: string
href: string
}
| {
id: string
title: string
children: (
| {
id: string
type: 'collection' | 'page'
}
| {
id: string
title: string
href: string
}
)[]
}
)[]
| null
footerLinks:
| (
| {
id: string
type: 'collection' | 'page'
}
| {
id: string
title: string
href: string
}
| {
id: string
title: string
children: (
| {
id: string
type: 'collection' | 'page'
}
| {
id: string
title: string
href: string
}
)[]
}
)[]
| null
footerLogoLink: string | null
footerTitle: string | null
footerImage: string | null
website: string | null
facebook: string | null
twitter: string | null
email: string | null
issn: string | null
isFeatured: boolean | null
viewHash: string | null
editHash: string | null
premiumLicenseFlag: boolean | null
defaultPubCollections: string[] | null
spamTagId: string | null
organizationId: string | null
scopeSummaryId: string | null
accentTextColor: string
createdAt?: string | undefined
updatedAt?: string | undefined
}
headers: Headers
}>pubpub.community.getCommunities
GET /api/communities
Get a list of communities. Currently only returns the current community.
getCommunities: (input?) =>
Promise<{
status: 200
body: {
id: string
subdomain: string
domain: string | null
title: string
citeAs: string | null
publishAs: string | null
description: string | null
avatar: string | null
favicon: string | null
accentColorLight: string
accentColorDark: string
hideCreatePubButton: boolean | null
headerLogo: string | null
headerLinks:
| { title: string; url: string; external?: boolean | undefined }[]
| null
headerColorType: 'light' | 'dark' | 'custom' | null
useHeaderTextAccent: boolean | null
hideHero: boolean | null
hideHeaderLogo: boolean | null
heroLogo: string | null
heroBackgroundImage: string | null
heroBackgroundColor: string | null
heroTextColor: string | null
useHeaderGradient: boolean | null
heroImage: string | null
heroTitle: string | null
heroText: string | null
heroPrimaryButton: { title: string; url: string } | null
heroSecondaryButton: { title: string; url: string } | null
heroAlign: string | null
navigation:
| (
| { id: string; type: 'collection' | 'page' }
| { id: string; title: string; href: string }
| {
id: string
title: string
children: (
| { id: string; type: 'collection' | 'page' }
| { id: string; title: string; href: string }
)[]
}
)[]
| null
hideNav: boolean | null
navLinks:
| (
| { id: string; type: 'collection' | 'page' }
| { id: string; title: string; href: string }
| {
id: string
title: string
children: (
| { id: string; type: 'collection' | 'page' }
| { id: string; title: string; href: string }
)[]
}
)[]
| null
footerLinks:
| (
| { id: string; type: 'collection' | 'page' }
| { id: string; title: string; href: string }
| {
id: string
title: string
children: (
| { id: string; type: 'collection' | 'page' }
| { id: string; title: string; href: string }
)[]
}
)[]
| null
footerLogoLink: string | null
footerTitle: string | null
footerImage: string | null
website: string | null
facebook: string | null
twitter: string | null
email