memorysync-sdk 1.2.0 → 1.4.0

package/dist/index.d.mts

@@ -26,6 +26,343 @@ declare class ServerError extends MemorySyncError {
     constructor(message: string, options?: ErrorOptions);
 }
 
+/**
+ * Connector namespaces — `client.connections`, `client.objects` and friends.
+ *
+ * Covers the connector API: creating and managing connections to Slack, Google
+ * Drive, S3 and Granola, driving syncs, and inspecting the objects a sync
+ * produced. Shaped after `client.connections.*` in comparable SDKs so the layout
+ * is familiar.
+ *
+ * ## Why these return raw payloads
+ *
+ * Connector responses are large, provider-shaped and still moving — a Slack
+ * channel listing looks nothing like an S3 prefix listing, and both carry
+ * provider fields that change when the provider changes. Freezing them into
+ * interfaces would mean an SDK release every time a provider adds a field, and
+ * callers unable to see the new field until then. Typed models are reserved for
+ * the small, stable, first-party shapes (memories, history, feedback, ontology).
+ */
+/** The client's request function, injected so namespaces carry no transport. */
+type RequestFn = <T>(method: string, path: string, options?: {
+    body?: unknown;
+    query?: Record<string, unknown>;
+}) => Promise<T>;
+type Json = Record<string, unknown>;
+declare class Namespace {
+    protected readonly req: RequestFn;
+    constructor(request: RequestFn);
+}
+/** Slack connection settings. */
+declare class SlackNamespace extends Namespace {
+    /**
+     * Channels the app can see and could be added.
+     *
+     * Private channels appear only where the deployment allows them *and* a human
+     * has invited the app, so this never widens what someone already granted.
+     */
+    availableChannels(connectionId: string, query?: Json): Promise<Json>;
+    /** Channels currently selected for syncing. */
+    channels(connectionId: string): Promise<Json>;
+    /**
+     * Select channels for syncing.
+     *
+     * Accepts bare channel ids, which is the common case, or objects carrying the
+     * name and type across so the server does not have to look them up again:
+     *
+     * ```ts
+     * await client.connections.slack.addChannels("c1", ["C0123", "C0456"]);
+     * await client.connections.slack.addChannels("c1", [
+     *   { id: "C0123", name: "support", is_private: false },
+     * ]);
+     * ```
+     */
+    addChannels(connectionId: string, channels: Array<string | Json>): Promise<Json>;
+    /** Stop syncing one channel. */
+    removeChannel(connectionId: string, channelId: string): Promise<Json>;
+    /**
+     * Channels this connection will never sync.
+     *
+     * The deployment-wide floor cannot be removed here; a tenant may only add to it.
+     */
+    exclusionPolicy(connectionId: string): Promise<Json>;
+    /** Replace this connection's additions to the exclusion policy. */
+    setExclusionPolicy(connectionId: string, policy: Json): Promise<Json>;
+    /** Slack users seen on this connection and who they map to. */
+    identities(connectionId: string): Promise<Json>;
+    /** Map a Slack user to a MemorySync end user. */
+    linkIdentity(connectionId: string, body: Json): Promise<Json>;
+    /** Re-read the Slack member list and refresh the identity table. */
+    syncIdentities(connectionId: string): Promise<Json>;
+}
+/** Google Drive connection settings. */
+declare class GoogleDriveNamespace extends Namespace {
+    /** Config for rendering Google's own file picker in your UI. */
+    pickerConfig(connectionId: string): Promise<Json>;
+    /** Files and folders selected for syncing. */
+    resources(connectionId: string, query?: Json): Promise<Json>;
+    /** Select files or folders for syncing. */
+    addResources(connectionId: string, body: Json): Promise<Json>;
+    /** Stop syncing one file or folder. */
+    removeResource(connectionId: string, resourceId: string): Promise<Json>;
+}
+/** S3 connection settings. */
+declare class S3Namespace extends Namespace {
+    /** Prefixes visible in the bucket that could be added. */
+    availablePrefixes(connectionId: string, query?: Json): Promise<Json>;
+    /** Prefixes currently selected for syncing. */
+    prefixes(connectionId: string): Promise<Json>;
+    /**
+     * Select prefixes for syncing.
+     *
+     * Accepts bare prefixes, or objects carrying `bucket` and `label`:
+     *
+     * ```ts
+     * await client.connections.s3.addPrefixes("c1", ["handbook/", "policies/"]);
+     * await client.connections.s3.addPrefixes("c1", [
+     *   { prefix: "handbook/", label: "Handbook" },
+     * ]);
+     * ```
+     *
+     * An empty string means the bucket root. The bucket defaults to the one the
+     * connection's credentials were validated against, and the API rejects any
+     * other bucket rather than indexing one nobody proved access to.
+     */
+    addPrefixes(connectionId: string, prefixes: Array<string | Json>): Promise<Json>;
+    /**
+     * Revoke one prefix approval, optionally purging what it produced.
+     *
+     * The prefix travels as a query parameter, not in the body and not as a path
+     * segment: prefixes contain slashes, which a path segment cannot carry
+     * unambiguously, and this endpoint reads no body at all.
+     *
+     * Pass `purge: true` to also delete the memories already derived from the
+     * prefix. The default leaves them in place, so revoking an approval does not
+     * silently destroy knowledge.
+     */
+    removePrefix(connectionId: string, prefix?: string, options?: {
+        bucket?: string;
+        purge?: boolean;
+    }): Promise<Json>;
+    /** Keys and patterns this connection will never sync. */
+    exclusionPolicy(connectionId: string): Promise<Json>;
+    /** Replace this connection's additions to the exclusion policy. */
+    setExclusionPolicy(connectionId: string, policy: Json): Promise<Json>;
+    /** Effective S3 settings, including the per-object size ceiling. */
+    settings(connectionId: string): Promise<Json>;
+}
+/** Granola connection settings. */
+declare class GranolaNamespace extends Namespace {
+    /** Folders that could be added. */
+    availableFolders(connectionId: string, query?: Json): Promise<Json>;
+    /** Folders currently selected for syncing. */
+    folders(connectionId: string): Promise<Json>;
+    /** Select folders for syncing. */
+    addFolders(connectionId: string, body: Json): Promise<Json>;
+    /** Stop syncing one folder. */
+    removeFolder(connectionId: string, folderId: string): Promise<Json>;
+    /** Folders and meetings this connection will never sync. */
+    exclusionPolicy(connectionId: string): Promise<Json>;
+    /** Replace this connection's additions to the exclusion policy. */
+    setExclusionPolicy(connectionId: string, policy: Json): Promise<Json>;
+    /** Meeting participants seen on this connection and who they map to. */
+    identities(connectionId: string): Promise<Json>;
+    /** Map a participant to a MemorySync end user. */
+    linkIdentity(connectionId: string, body: Json): Promise<Json>;
+    /**
+     * Re-run identity matching for this connection.
+     *
+     * Takes no arguments: the route reads no body and re-matches the whole roster.
+     * `body` is kept optional only so a forward-compatible field can be passed
+     * once the route grows one.
+     */
+    relinkIdentity(connectionId: string, body?: Json): Promise<Json>;
+    /** Effective Granola settings for this connection. */
+    settings(connectionId: string): Promise<Json>;
+    /** Update Granola settings for this connection. */
+    setSettings(connectionId: string, settings: Json): Promise<Json>;
+}
+/** Starting an OAuth connection. */
+declare class ConnectionOAuthNamespace extends Namespace {
+    /**
+     * Begin an OAuth connection and get the URL to send the user to.
+     *
+     * The user completes consent in a browser and the provider calls the platform
+     * back — not your backend. Poll {@link status} to find out how it went.
+     */
+    initiate(provider: string, body?: Json): Promise<Json>;
+    /** Where an in-flight OAuth connection got to. */
+    status(query?: Json): Promise<Json>;
+}
+/**
+ * Connections to external sources.
+ *
+ * Provider-specific settings live in sub-namespaces: `connections.slack`,
+ * `connections.gdrive`, `connections.s3`, `connections.granola`.
+ */
+declare class ConnectionsNamespace extends Namespace {
+    readonly slack: SlackNamespace;
+    readonly gdrive: GoogleDriveNamespace;
+    readonly s3: S3Namespace;
+    readonly granola: GranolaNamespace;
+    readonly oauth: ConnectionOAuthNamespace;
+    constructor(request: RequestFn);
+    /** Every connection in this organization. */
+    list(query?: Json): Promise<Json>;
+    /** One connection, including its status and last sync. */
+    get(connectionId: string): Promise<Json>;
+    /** Connect a provider that authenticates with an API key or bot token. */
+    /**
+     * Connect a provider that authenticates with an API key or bot token.
+     *
+     * The wire field is `provider_id`; the argument is named `provider` because
+     * that is what the rest of this namespace calls it.
+     */
+    createWithApiKey(provider: string, apiKey: string, body?: Json): Promise<Json>;
+    /** Connect a provider that needs a credential bundle, such as S3 keys. */
+    createWithCredentials(provider: string, credentials: Json, body?: Json): Promise<Json>;
+    /** Change a connection's name, schedule or settings. */
+    update(connectionId: string, body: Json): Promise<Json>;
+    /**
+     * Remove a connection.
+     *
+     * Stops future syncing. Memories already extracted are left in place — use
+     * {@link purge} for those, so disconnecting never silently deletes knowledge
+     * someone still depends on.
+     */
+    delete(connectionId: string): Promise<Json>;
+    /** Re-authorise a connection whose credentials expired or were revoked. */
+    reconnect(connectionId: string, body?: Json): Promise<Json>;
+    /**
+     * Delete the memories this connection produced.
+     *
+     * Separate from {@link delete} on purpose: removing a connection and removing
+     * what it taught you are different decisions.
+     */
+    purge(connectionId: string, body?: Json): Promise<Json>;
+    /** Current and recent sync state for a connection. */
+    syncStatus(connectionId: string): Promise<Json>;
+    /** Start a sync now instead of waiting for the schedule. */
+    triggerSync(connectionId: string, body?: Json): Promise<Json>;
+    /** Objects a connection has ingested — files, messages, meetings. */
+    objects(connectionId: string, query?: Json): Promise<Json>;
+    /** Object listing with richer filtering and paging than {@link objects}. */
+    objectsV2(connectionId: string, query?: Json): Promise<Json>;
+    /** Apply one action to many objects — pause, resume, re-extract. */
+    bulkObjectAction(connectionId: string, body: Json): Promise<Json>;
+    /** Connector totals: connections, objects synced, memories produced. */
+    stats(query?: Json): Promise<Json>;
+    /** Audit trail of connector activity. */
+    auditLogs(query?: Json): Promise<Json>;
+}
+/**
+ * A single synced object: a Drive file, a Slack message batch, an S3 key, a
+ * meeting transcript.
+ */
+declare class ObjectsNamespace extends Namespace {
+    /** Metadata and sync state for one object. */
+    get(objectId: string): Promise<Json>;
+    /** What extraction made of this object. */
+    analysis(objectId: string): Promise<Json>;
+    /** Every action taken on this object. */
+    audit(objectId: string, query?: Json): Promise<Json>;
+    /** Versions of this object seen across syncs. */
+    history(objectId: string, query?: Json): Promise<Json>;
+    /** Which memories this object produced, and whether extraction finished. */
+    memoryStatus(objectId: string): Promise<Json>;
+    /** Row and column statistics for spreadsheet-shaped objects. */
+    structuredStats(objectId: string): Promise<Json>;
+    /** Score this object for extraction worthiness without extracting. */
+    evaluate(objectId: string, body?: Json): Promise<Json>;
+    /** Stop re-syncing this object, leaving its memories in place. */
+    pause(objectId: string): Promise<Json>;
+    /** Resume syncing a paused object. */
+    resume(objectId: string): Promise<Json>;
+    /**
+     * Run extraction again over content already fetched.
+     *
+     * Counts against the plan's add allowance, exactly like the first extraction,
+     * because it creates memories the same way.
+     */
+    reextract(objectId: string, body?: Json): Promise<Json>;
+    /** Fetch this object from the provider again, then extract. */
+    resync(objectId: string, body?: Json): Promise<Json>;
+    /** Remove the memories this object produced, keeping the object record. */
+    deleteMemories(objectId: string, query?: Json): Promise<Json>;
+}
+/** Connectors this deployment supports. */
+declare class ProvidersNamespace extends Namespace {
+    /** Every available provider and what it needs to connect. */
+    list(query?: Json): Promise<Json>;
+    /** One provider's capabilities, scopes and settings schema. */
+    get(providerId: string): Promise<Json>;
+}
+/** Individual sync runs. */
+declare class SyncJobsNamespace extends Namespace {
+    /** Progress and outcome of one sync run. */
+    get(jobId: string): Promise<Json>;
+    /** Stop a running sync. Objects already ingested are kept. */
+    cancel(jobId: string, body?: Json): Promise<Json>;
+}
+/** Turn websites into memories. */
+declare class WebCrawlerNamespace extends Namespace {
+    /** Check a URL is reachable and crawlable before committing to a job. */
+    validate(url: string, body?: Json): Promise<Json>;
+    /**
+     * Start a crawl. Returns a job to poll.
+     *
+     * Crawling only fetches and stores page content. Nothing becomes a memory until
+     * you call {@link importJob}, so a large crawl cannot quietly consume your add
+     * allowance.
+     */
+    crawl(url: string, body?: Json): Promise<Json>;
+    /** Crawl jobs for this organization. */
+    jobs(query?: Json): Promise<Json>;
+    /** One crawl job's status and progress. */
+    job(jobId: string): Promise<Json>;
+    /** Stop a running crawl. Pages already fetched are kept. */
+    cancelJob(jobId: string): Promise<Json>;
+    /** Delete a crawl job and its fetched pages. */
+    deleteJob(jobId: string): Promise<Json>;
+    /** Pages a crawl fetched, before any import. */
+    jobContent(jobId: string, query?: Json): Promise<Json>;
+    /** Page counts, byte totals and error breakdown for a crawl. */
+    jobStatistics(jobId: string): Promise<Json>;
+    /**
+     * Turn a completed crawl's pages into memories.
+     *
+     * This is the step that creates memories, so this is the step that is billed —
+     * one unit per memory created, like every other ingestion path.
+     */
+    importJob(jobId: string, body?: Json): Promise<Json>;
+    /** Crawls running right now. */
+    active(): Promise<Json>;
+    /** Crawler limits in force: depth, page ceiling, rate, timeouts. */
+    config(): Promise<Json>;
+}
+/**
+ * The `/api/v1/integrations` surface.
+ *
+ * Kept because the catalog and the web crawler live here and have no v2
+ * equivalent. For connection lifecycle use `client.connections`, which is the
+ * current API — `connected()` and `stats()` here are older, thinner views of the
+ * same data.
+ */
+declare class IntegrationsNamespace extends Namespace {
+    readonly webCrawler: WebCrawlerNamespace;
+    constructor(request: RequestFn);
+    /** Every integration this deployment offers, for building a picker UI. */
+    catalog(query?: Json): Promise<Json>;
+    /** Integrations currently connected. Older view of `connections.list()`. */
+    connected(query?: Json): Promise<Json>;
+    /** Legacy integration counters. Prefer `connections.stats()`. */
+    stats(query?: Json): Promise<Json>;
+    /** Update a legacy integration record. */
+    update(integrationId: string, body: Json): Promise<Json>;
+    /** Delete a legacy integration record. */
+    delete(integrationId: string): Promise<Json>;
+}
+
 interface ControlPlaneConfig {
     baseUrl: string;
     accessToken?: string;
@@ -679,6 +1016,7 @@ interface UploadRequest {
     metadata?: Record<string, unknown>;
     endUserId?: string;
 }
+
 declare class MemorySyncClient {
     private readonly apiKey;
     private readonly baseUrl;
@@ -686,6 +1024,16 @@ declare class MemorySyncClient {
     private readonly endUserId?;
     private readonly timeoutMs;
     private readonly fetchImpl;
+    /** Connections to external sources, with provider sub-namespaces. */
+    readonly connections: ConnectionsNamespace;
+    /** Individual objects a connector ingested. */
+    readonly objects: ObjectsNamespace;
+    /** Connectors this deployment supports. */
+    readonly providers: ProvidersNamespace;
+    /** Individual sync runs. */
+    readonly syncJobs: SyncJobsNamespace;
+    /** The legacy `/api/v1/integrations` surface, including the web crawler. */
+    readonly integrations: IntegrationsNamespace;
     constructor(config: MemorySyncConfig);
     private headers;
     private request;
@@ -872,4 +1220,4 @@ declare class MemorySyncClient {
     }): Promise<Record<string, unknown>>;
 }
 
-export { type AddRequest, type AddResponse, type AddSkippedResponse, type ApiKeyTestResponse, type ApiKeyTestStatus, type AuditActor, type AuditEvent, type AuditEventListResponse, type AuditEventQuery, type AuditResource, type AuditSortDirection, AuthError, type BatchUpdateItem, type BatchUpdateItemResult, type BatchUpdateResponse, type BulkAddItem, type BulkAddItemResult, type BulkAddResponse, type BulkRevokeApiKeyResult, type BulkRevokeApiKeysRequest, type BulkRevokeApiKeysResponse, type ComposeRequest, type ComposeResponse, ControlPlaneClient, type ControlPlaneConfig, type ControlPlaneRequestOptions, type CreateOrganizationRequest, type CreateWebhookRequest, type CreatedWebhook, type CurrentPlanResponse, type ExportResponse, type FeedbackResponse, type FeedbackSignal, type FeedbackSummary, type FeedbackTrend, type ForgetFilters, type ForgetRequest, type HistoryResponse, type Integration, type IntegrationQuery, type LoginRequest, type LoginResponse, type MemoryRecord, MemorySyncClient, type MemorySyncConfig, MemorySyncError, NotFoundError, type Ontology, type OntologyUpdateRequest, type OrganizationMembership, type OrganizationSettings, type OrganizationSettingsQuery, type Plan, type PlanLimits, type Project, type QueryFilters, type QueryRequest, type QueryResponse, RateLimitError, type RelationCreateRequest, type RelationRecord, type RelationshipType, type ReplayWebhookDeliveriesRequest, type ReplayWebhookDeliveriesResponse, type RevisionEntry, type RevisionEvent, ServerError, type Session, type SessionListResponse, type SummarizeRequest, type TeamMember, type TestWebhookRequest, type TestWebhookResponse, type UpdateRequest, type UpdateWebhookRequest, type UploadRequest, ValidationError, type Webhook, type WebhookDelivery, type WebhookDeliveryListResponse, type WebhookDeliveryQuery, type WebhookListResponse, type WebhookRetryConfig, type WebhookSignatureConfig };
+export { type AddRequest, type AddResponse, type AddSkippedResponse, type ApiKeyTestResponse, type ApiKeyTestStatus, type AuditActor, type AuditEvent, type AuditEventListResponse, type AuditEventQuery, type AuditResource, type AuditSortDirection, AuthError, type BatchUpdateItem, type BatchUpdateItemResult, type BatchUpdateResponse, type BulkAddItem, type BulkAddItemResult, type BulkAddResponse, type BulkRevokeApiKeyResult, type BulkRevokeApiKeysRequest, type BulkRevokeApiKeysResponse, type ComposeRequest, type ComposeResponse, ConnectionOAuthNamespace, ConnectionsNamespace, ControlPlaneClient, type ControlPlaneConfig, type ControlPlaneRequestOptions, type CreateOrganizationRequest, type CreateWebhookRequest, type CreatedWebhook, type CurrentPlanResponse, type ExportResponse, type FeedbackResponse, type FeedbackSignal, type FeedbackSummary, type FeedbackTrend, type ForgetFilters, type ForgetRequest, GoogleDriveNamespace, GranolaNamespace, type HistoryResponse, type Integration, type IntegrationQuery, IntegrationsNamespace, type LoginRequest, type LoginResponse, type MemoryRecord, MemorySyncClient, type MemorySyncConfig, MemorySyncError, NotFoundError, ObjectsNamespace, type Ontology, type OntologyUpdateRequest, type OrganizationMembership, type OrganizationSettings, type OrganizationSettingsQuery, type Plan, type PlanLimits, type Project, ProvidersNamespace, type QueryFilters, type QueryRequest, type QueryResponse, RateLimitError, type RelationCreateRequest, type RelationRecord, type RelationshipType, type ReplayWebhookDeliveriesRequest, type ReplayWebhookDeliveriesResponse, type RevisionEntry, type RevisionEvent, S3Namespace, ServerError, type Session, type SessionListResponse, SlackNamespace, type SummarizeRequest, SyncJobsNamespace, type TeamMember, type TestWebhookRequest, type TestWebhookResponse, type UpdateRequest, type UpdateWebhookRequest, type UploadRequest, ValidationError, WebCrawlerNamespace, type Webhook, type WebhookDelivery, type WebhookDeliveryListResponse, type WebhookDeliveryQuery, type WebhookListResponse, type WebhookRetryConfig, type WebhookSignatureConfig };