Skip to main content

UpgatherService

Upgather SDK

Upgather SDK / UpgatherService

Class: UpgatherService

Defined in: lib/services/UpgatherService.ts:129

A façade that exposes all SDK capabilities through a single, ergonomic API. Combines StrapiService and VectorStoreService functionality into a unified interface.

Example​

const upgather = new UpgatherService({
  url: "https://cms.example.com",
  token: process.env.STRAPI_TOKEN,
  openAiKey: process.env.OPENAI_KEY,
});

// Raw Strapi access (fully typed)
const event = await upgather.type("Event").get("lsrl618nk7h2716jcun4ayaj", {
  populate: ["organization", "vector_store"],
});

// Vector store helpers
await upgather.addVectorFile(event.id, { path: "/tmp/file.md" });

// Event convenience methods
const activeEvents = await upgather.events.queryActive();

Constructors​

new UpgatherService()​

new UpgatherService(config): UpgatherService

Defined in: lib/services/UpgatherService.ts:140

Creates an instance of UpgatherService.

Parameters​

config​

UpgatherConfig

Configuration options for the service

Returns​

UpgatherService

Properties​

events​

readonly events: object

Defined in: lib/services/UpgatherService.ts:311

Common event operations that combine Strapi and vector store functionality. These are convenience methods for common workflows.

addDocument()​

addDocument: (eventId, file, filename?) => Promise<UploadedFile>

Add a document to an event's vector store with automatic error handling.

Parameters​
eventId​

string

The event ID

file​

The file to upload (Buffer, Readable, or FileObject)

FileObject | Buffer<ArrayBufferLike> | Readable

filename?​

string

Optional filename when providing a Buffer

Returns​

Promise<UploadedFile>

The uploaded file information

Example​
try {
  const doc = await upgather.events.addDocument(eventId, buffer, "report.pdf");
} catch (error) {
  // Error is automatically logged and re-thrown
}

getWithDetails()​

getWithDetails: (eventId) => Promise<ApiEventEventEntity>

Get an event with common relations populated.

Parameters​
eventId​

The event ID

string | number

Returns​

Promise<ApiEventEventEntity>

The event with sessions, speakers, and sponsors populated

Example​
const event = await upgather.events.getWithDetails(eventId);

Methods​

addVectorFile()​

addVectorFile(eventId, file, filename?, options?): Promise<UploadedFile>

Defined in: lib/services/UpgatherService.ts:232

Upload a new file to the vector store associated with the specified Event.

Parameters​

eventId​

string

Strapi Event ID

file​

Buffer, Readable, or FileObject to upload

FileObject | Buffer<ArrayBufferLike> | Readable

filename?​

string

Optional filename when providing a Buffer

options?​

VectorStoreOptions

Optional overrides for the OpenAI key

Returns​

Promise<UploadedFile>

The uploaded file information

Example​

// Upload a buffer
const uploaded = await upgather.addVectorFile(eventId, buffer, "document.pdf");

// Upload a file from disk
const uploaded = await upgather.addVectorFile(eventId, { path: "/tmp/file.md" });

get()​

get<K>(contentType, id, params?): Promise<EntityType<K>>

Defined in: lib/services/UpgatherService.ts:206

Convenience helper for simple one-off Strapi GETs without calling type.

Type Parameters​

• K extends keyof StrapiContentMapping

A key from StrapiContentMapping corresponding to a content type

Parameters​

contentType​

K

The friendly name of the content type

id​

The ID of the entry

string | number

params?​

StrapiQueryParams

Optional query parameters (e.g. populate, fields, locale, status, etc.)

Returns​

Promise<EntityType<K>>

A promise resolving to a typed content entry

Example​

const event = await upgather.get("Event", eventId, { populate: ["organization"] });

getLogger()​

getLogger(): LoggerInterface

Defined in: lib/services/UpgatherService.ts:170

Gets the logger instance used by this service.

Returns​

LoggerInterface

The logger instance

Remarks​

This method allows access to the logger for debugging purposes or to pass it to other components. The logger instance is shared across all SDK components including ApiClient, StrapiService, and VectorStoreService.

removeVectorFile()​

removeVectorFile(eventId, fileId, options?): Promise<FileDeleted & object>

Defined in: lib/services/UpgatherService.ts:295

Remove a document from the vector store and delete it from OpenAI.

Parameters​

eventId​

string

Strapi Event ID

fileId​

string

ID of the file to remove

options?​

VectorStoreOptions

Optional overrides for the OpenAI key

Returns​

Promise<FileDeleted & object>

The OpenAI delete response (usually { deleted: true })

Example​

await upgather.removeVectorFile(eventId, fileId);

type()​

type<K>(contentType): object

Defined in: lib/services/UpgatherService.ts:188

Generic passthrough for any Strapi content type.

Type Parameters​

• K extends keyof StrapiContentMapping

A key from StrapiContentMapping corresponding to a content type

Parameters​

contentType​

K

The friendly name of the content type

Returns​

object

An object with methods for performing CRUD operations on the specified content type

create()​

create: (data, params?) => Promise<EntityType<K>>

Create a new entry with proper entity typing.

Parameters​
data​

Partial<EntityType<K>>

The data for the new entry.

params?​

StrapiQueryParams

Optional query parameters (e.g. locale).

Returns​

Promise<EntityType<K>>

A promise resolving to the created entity.

Example​
// Create a new app.
await strapiService.type('App').create({ integrationOrgId: '123', integrationType: 'eventbrite' }, { locale: 'en' });
delete()​

delete: (id, params?) => Promise<EntityType<K>>

Delete an entry by its ID with proper entity typing.

Parameters​
id​

The ID of the entry.

string | number

params?​

StrapiQueryParams

Optional query parameters (e.g. locale).

Returns​

Promise<EntityType<K>>

A promise resolving to the deleted entity.

Example​
// Delete an app.
await strapiService.type('App').delete(123, { locale: 'en' });
get()​

get: (id, params?) => Promise<EntityType<K>>

Fetch a single entry by its ID with proper entity typing.

Parameters​
id​

The ID of the entry.

string | number

params?​

StrapiQueryParams

Optional query parameters (e.g. populate, fields, locale, status, etc.).

Returns​

Promise<EntityType<K>>

A promise resolving to a typed entity.

Example​
// Retrieve a single app with id '123'
await strapiService.type('App').get(123, { populate: ['organization'] });
mergeUpdate()​

mergeUpdate: (id, changes, params?) => Promise<EntityType<K>>

Safely update an entry using the GET-merge-PUT pattern.

Strapi v5 PUT is a full replace — any field not included in the body gets nullified. This method GETs the current published state, strips system fields, merges the provided changes, and PUTs the complete merged document back with ?status=published.

Parameters​
id​

The documentId of the entry.

string | number

changes​

Partial<EntityType<K>>

Partial data to merge onto the current record.

params?​

StrapiQueryParams

Optional query parameters for the PUT (defaults to { status: 'published' }).

Returns​

Promise<EntityType<K>>

A promise resolving to the updated entity.

Example​
await strapiService.type('Speaker').mergeUpdate('abc123', { title: 'New Title' });
query()​

query: (params?) => Promise<EntityType<K>[]>

Query multiple entries using URL parameters with proper entity typing.

Parameters​
params?​

StrapiQueryParams

Optional query parameters.

Returns​

Promise<EntityType<K>[]>

A promise resolving to an array of typed entities.

Example​
// Query apps with filters and pagination.
await strapiService.type('App').query({ filters: { integrationType: { $eq: 'eventbrite' } }, pagination: { page: 1, pageSize: 10 } });
update()​

update: (id, data, params?) => Promise<EntityType<K>>

Update an existing entry by its ID with proper entity typing.

Parameters​
id​

The ID of the entry.

string | number

data​

Partial<EntityType<K>>

The updated data for the entry.

params?​

StrapiQueryParams

Optional query parameters (e.g. locale).

Returns​

Promise<EntityType<K>>

A promise resolving to the updated entity.

Example​
// Update an app.
await strapiService.type('App').update(123, { isConnected: true }, { locale: 'en' });

Example​

const articles = await upgather.type("Article").query({ sort: "publishedAt:desc" });
const event = await upgather.type("Event").get(123);
const newArticle = await upgather.type("Article").create({ title: "New Article" });

updateVectorFile()​

updateVectorFile(eventId, oldFileId, newFile, filename?, options?): Promise<UploadedFile>

Defined in: lib/services/UpgatherService.ts:266

Replace an existing vector store document with a new one.

Parameters​

eventId​

string

Strapi Event ID

oldFileId​

string

ID of the file to replace

newFile​

New file (Buffer, Readable, or FileObject)

FileObject | Buffer<ArrayBufferLike> | Readable

filename?​

string

Optional filename when providing a Buffer

options?​

VectorStoreOptions

Optional overrides for the OpenAI key

Returns​

Promise<UploadedFile>

The new uploaded file information

Example​

const updated = await upgather.updateVectorFile(
  eventId,
  oldFileId,
  newBuffer,
  "updated-document.pdf"
);