@sofia-post/node 0.0.0-stage → 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Sofia
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,65 @@
-# Temporary Holding Version
+# Sofia Node.js SDK
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+The official Node.js SDK for [Sofia API](https://www.sofia-post.com/developers/reference): publish, schedule and read your social posts from your own code.
+
+```bash
+npm install @sofia-post/node
+```
+
+Node.js 20 or later. No dependencies: the SDK uses the `fetch`, `FormData` and `Blob` built into Node.
+
+## Usage
+
+```ts
+import { Sofia } from '@sofia-post/node';
+
+const sofia = new Sofia(process.env.SOFIA_API_KEY);
+
+const [establishment] = await sofia.establishments();
+
+const post = await sofia.post({
+  establishmentId: establishment.id,
+  targets: [{ platform: 'instagram', text: 'Tarte tatin du jour 🍎' }],
+  scheduledAt: new Date('2026-12-01T09:00:00Z'),
+});
+```
+
+The key is a personal key (`sofia_pk_live_…`, or `sofia_pk_test_…` for the sandbox) created in **Settings › API**, **Personal access** tab, or an OAuth access token. A second argument changes the base URL: `new Sofia(key, { baseUrl: 'http://localhost:3008' })`.
+
+## Methods
+
+| Method                                                                          | What it does                                                   |
+| ------------------------------------------------------------------------------- | -------------------------------------------------------------- |
+| `me()`                                                                          | Who the key acts for, its scopes, test or live                 |
+| `platforms()`                                                                   | Each network's rules: caption length, media, formats           |
+| `establishments()`                                                              | The establishments the key reaches                             |
+| `accounts(establishmentId)`                                                     | The connected social accounts of an establishment              |
+| `connectionLink(establishmentId, input)`                                        | A hosted page where the person connects a network              |
+| `insights(establishmentId, period?)`                                            | Reach, engagement and followers per network                    |
+| `post(input, { dryRun?, idempotencyKey? })`                                     | Publish now, schedule (`scheduledAt`) or save a draft          |
+| `postList(filters?)`                                                            | A page of posts, filtered by establishment, status or dates    |
+| `getPost(id)`                                                                   | One post and the state of each network                         |
+| `updatePost(id, input)`                                                         | Change the text, media or date of a post not yet published     |
+| `deletePost(id)`                                                                | Withdraw a post                                                |
+| `upload({ establishmentId, file, fileName })`                                   | Add a file to the library (a `Buffer`, `Uint8Array` or `Blob`) |
+| `uploadFromUrl({ establishmentId, url })`                                       | Let Sofia download a file into the library                     |
+| `mediaList(filters)` · `getMedia(id)` · `deleteMedia(id)`                       | Read and clean the library                                     |
+| `createWebhook(input)` · `webhooks()` · `deleteWebhook(id)` · `testWebhook(id)` | Be told when a post goes out or fails                          |
+
+## Errors
+
+Every method throws a `SofiaApiError` on failure, with the API's `status`, a stable `code`, `details` (the network rules a post breaks, for instance), `requestId` and, on 429, `retryAfterSeconds`. When the API cannot be reached, `code` is `network_error` and `status` is 0.
+
+```ts
+import { SofiaApiError } from '@sofia-post/node';
+
+try {
+  await sofia.post(input);
+} catch (error) {
+  if (error instanceof SofiaApiError && error.code === 'post_refused') {
+    console.log(error.details);
+  }
+}
+```
+
+Full documentation: [sofia-post.com/developers/node-sdk](https://www.sofia-post.com/developers/node-sdk).

package/package.json

@@ -1,6 +1,32 @@
 {
   "name": "@sofia-post/node",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "0.1.0",
+  "description": "Official Node.js SDK for the Sofia API: publish, schedule and read your social posts from your own code.",
+  "type": "commonjs",
+  "main": "./src/index.js",
+  "types": "./src/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./src/index.d.ts",
+      "default": "./src/index.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "engines": {
+    "node": ">=20"
+  },
+  "license": "MIT",
+  "homepage": "https://www.sofia-post.com/developers/node-sdk",
+  "keywords": [
+    "sofia",
+    "social-media",
+    "publishing",
+    "scheduling",
+    "sdk",
+    "api"
+  ],
+  "author": "Sofia <contact@sofia-post.com>",
+  "bugs": {
+    "email": "contact@sofia-post.com"
+  }
 }

package/src/index.d.ts

@@ -0,0 +1,7 @@
+export { DEFAULT_BASE_URL, Sofia, type SofiaOptions } from './lib/client/sofia';
+export { SofiaApiError, type SofiaApiErrorDetail } from './lib/http/sofia-api-error';
+export type { Platform, Instant, PostMedia, PostTarget, PublishPostInput, PublishPostOptions, EditPostInput, TargetState, LivePostTarget, LivePost, SandboxPost, CreatedLivePost, CheckedPost, Post, PublishedPost, ListPostsFilters, Page, } from './lib/posts/post.types';
+export type { MediaType, Media, MediaListItem, UploadableFile, UploadInput, UploadFromUrlInput, ListMediaFilters, } from './lib/media/media.types';
+export type { Establishment, SocialAccount, ConnectionLinkInput, ConnectionLink, InsightsPeriod, MetricReading, NetworkInsights, EstablishmentInsights, } from './lib/establishments/establishment.types';
+export type { WebhookEvent, RegisterWebhookInput, Webhook, CreatedWebhook, WebhookTest, } from './lib/webhooks/webhook.types';
+export type { Scope, Me, PlatformRules } from './lib/discovery/discovery.types';

package/src/index.js

@@ -0,0 +1,8 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SofiaApiError = exports.Sofia = exports.DEFAULT_BASE_URL = void 0;
+var sofia_1 = require("./lib/client/sofia");
+Object.defineProperty(exports, "DEFAULT_BASE_URL", { enumerable: true, get: function () { return sofia_1.DEFAULT_BASE_URL; } });
+Object.defineProperty(exports, "Sofia", { enumerable: true, get: function () { return sofia_1.Sofia; } });
+var sofia_api_error_1 = require("./lib/http/sofia-api-error");
+Object.defineProperty(exports, "SofiaApiError", { enumerable: true, get: function () { return sofia_api_error_1.SofiaApiError; } });

package/src/lib/client/sofia.d.ts

@@ -0,0 +1,57 @@
+import type { Me, PlatformRules } from '../discovery/discovery.types';
+import type { ConnectionLink, ConnectionLinkInput, Establishment, EstablishmentInsights, InsightsPeriod, SocialAccount } from '../establishments/establishment.types';
+import type { ListMediaFilters, Media, MediaListItem, UploadFromUrlInput, UploadInput } from '../media/media.types';
+import type { CheckedPost, CreatedLivePost, EditPostInput, ListPostsFilters, LivePost, Page, Post, PublishedPost, PublishPostInput, PublishPostOptions, SandboxPost } from '../posts/post.types';
+import type { CreatedWebhook, RegisterWebhookInput, Webhook, WebhookTest } from '../webhooks/webhook.types';
+export declare const DEFAULT_BASE_URL = "https://api.sofia-post.com";
+export type SofiaOptions = {
+    /** `https://api.sofia-post.com` by default. */
+    readonly baseUrl?: string;
+    /** The `fetch` to send requests with: the global one by default (Node 20+). */
+    readonly fetch?: typeof fetch;
+};
+/**
+ * The Sofia API v1 client. One instance per key: a personal key (`sofia_pk_live_…`,
+ * `sofia_pk_test_…`) or an OAuth access token. Every method throws a `SofiaApiError` on failure.
+ */
+export declare class Sofia {
+    private readonly http;
+    /** `apiKey` may come straight from `process.env`: an absent or empty key throws here, before any request. */
+    constructor(apiKey: string | undefined, options?: SofiaOptions);
+    /** Who the key acts for, its scopes, and whether it is a test key. */
+    me(): Promise<Me>;
+    /** Each network's rules: caption length, media, formats. */
+    platforms(): Promise<readonly PlatformRules[]>;
+    establishments(): Promise<readonly Establishment[]>;
+    /** The connected social accounts of an establishment: Postiz's `integrations()`. */
+    accounts(establishmentId: string): Promise<readonly SocialAccount[]>;
+    /** A page hosted by Sofia where the person connects a network to the establishment. */
+    connectionLink(establishmentId: string, input: ConnectionLinkInput): Promise<ConnectionLink>;
+    insights(establishmentId: string, period?: InsightsPeriod): Promise<EstablishmentInsights>;
+    /** A dry run writes nothing: it answers the post Sofia would accept, or throws its refusal. */
+    post(input: PublishPostInput, options: PublishPostOptions & {
+        dryRun: true;
+    }): Promise<CheckedPost>;
+    /** Publishes now, schedules (`scheduledAt`) or saves a draft (`status: 'draft'`). */
+    post(input: PublishPostInput, options?: PublishPostOptions & {
+        dryRun?: false;
+    }): Promise<CreatedLivePost | SandboxPost>;
+    post(input: PublishPostInput, options?: PublishPostOptions): Promise<PublishedPost>;
+    postList(filters?: ListPostsFilters): Promise<Page<Post>>;
+    getPost(id: string): Promise<Post>;
+    updatePost(id: string, input: EditPostInput): Promise<LivePost>;
+    /** Withdraws the post from every network it was scheduled on. */
+    deletePost(id: string): Promise<void>;
+    /** Adds a file to the establishment's library; its `id` then goes in a post's `media`. */
+    upload(input: UploadInput): Promise<Media>;
+    /** Sofia downloads the file at `url` itself. */
+    uploadFromUrl({ establishmentId, url, idempotencyKey }: UploadFromUrlInput): Promise<Media>;
+    mediaList(filters: ListMediaFilters): Promise<Page<MediaListItem>>;
+    getMedia(id: string): Promise<Media>;
+    deleteMedia(id: string): Promise<void>;
+    createWebhook(input: RegisterWebhookInput): Promise<CreatedWebhook>;
+    webhooks(): Promise<readonly Webhook[]>;
+    deleteWebhook(id: string): Promise<void>;
+    /** Sends a test delivery, signed like a real one. */
+    testWebhook(id: string): Promise<WebhookTest>;
+}

package/src/lib/client/sofia.js

@@ -0,0 +1,135 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.Sofia = exports.DEFAULT_BASE_URL = void 0;
+const content_type_1 = require("../http/content-type");
+const path_of_1 = require("../http/path-of");
+const sdk_version_1 = require("../http/sdk-version");
+const sofia_http_client_1 = require("../http/sofia-http-client");
+exports.DEFAULT_BASE_URL = 'https://api.sofia-post.com';
+const blobOf = ({ file, fileName, contentType }) => {
+    const type = contentType ?? (0, content_type_1.contentTypeOf)(fileName);
+    return new Blob([file instanceof Blob ? file : new Uint8Array(file)], { type });
+};
+/**
+ * The Sofia API v1 client. One instance per key: a personal key (`sofia_pk_live_…`,
+ * `sofia_pk_test_…`) or an OAuth access token. Every method throws a `SofiaApiError` on failure.
+ */
+class Sofia {
+    /** `apiKey` may come straight from `process.env`: an absent or empty key throws here, before any request. */
+    constructor(apiKey, options = {}) {
+        if (apiKey === undefined || apiKey.trim() === '') {
+            throw new TypeError('Sofia needs an API key: new Sofia(apiKey)');
+        }
+        this.http = new sofia_http_client_1.SofiaHttpClient({
+            apiKey,
+            baseUrl: (options.baseUrl ?? exports.DEFAULT_BASE_URL).replace(/\/+$/, ''),
+            userAgent: `sofia-node/${sdk_version_1.SDK_VERSION}`,
+            fetch: options.fetch ?? globalThis.fetch,
+        });
+    }
+    /** Who the key acts for, its scopes, and whether it is a test key. */
+    me() {
+        return this.http.send({ method: 'GET', path: '/me' });
+    }
+    /** Each network's rules: caption length, media, formats. */
+    async platforms() {
+        return (await this.http.send({ method: 'GET', path: '/platforms' })).data;
+    }
+    async establishments() {
+        const list = await this.http.send({
+            method: 'GET',
+            path: '/establishments',
+        });
+        return list.data;
+    }
+    /** The connected social accounts of an establishment: Postiz's `integrations()`. */
+    async accounts(establishmentId) {
+        const path = (0, path_of_1.pathOf)('establishments', establishmentId, 'accounts');
+        return (await this.http.send({ method: 'GET', path })).data;
+    }
+    /** A page hosted by Sofia where the person connects a network to the establishment. */
+    connectionLink(establishmentId, input) {
+        const path = (0, path_of_1.pathOf)('establishments', establishmentId, 'connection-links');
+        return this.http.send({ method: 'POST', path, body: { kind: 'json', value: input } });
+    }
+    insights(establishmentId, period) {
+        const path = (0, path_of_1.pathOf)('establishments', establishmentId, 'insights');
+        return this.http.send({ method: 'GET', path, query: { period } });
+    }
+    post(input, options = {}) {
+        return this.http.send({
+            method: 'POST',
+            path: '/posts',
+            query: { dry_run: options.dryRun ? 'true' : undefined },
+            body: { kind: 'json', value: input },
+            idempotencyKey: options.idempotencyKey,
+        });
+    }
+    postList(filters = {}) {
+        return this.http.send({ method: 'GET', path: '/posts', query: filters });
+    }
+    getPost(id) {
+        return this.http.send({ method: 'GET', path: (0, path_of_1.pathOf)('posts', id) });
+    }
+    updatePost(id, input) {
+        return this.http.send({
+            method: 'PATCH',
+            path: (0, path_of_1.pathOf)('posts', id),
+            body: { kind: 'json', value: input },
+        });
+    }
+    /** Withdraws the post from every network it was scheduled on. */
+    async deletePost(id) {
+        await this.http.send({ method: 'DELETE', path: (0, path_of_1.pathOf)('posts', id) });
+    }
+    /** Adds a file to the establishment's library; its `id` then goes in a post's `media`. */
+    upload(input) {
+        return this.http.send({
+            method: 'POST',
+            path: '/media',
+            body: {
+                kind: 'multipart',
+                fields: { establishmentId: input.establishmentId },
+                file: { field: 'file', name: input.fileName, blob: blobOf(input) },
+            },
+            idempotencyKey: input.idempotencyKey,
+        });
+    }
+    /** Sofia downloads the file at `url` itself. */
+    uploadFromUrl({ establishmentId, url, idempotencyKey }) {
+        const value = { establishmentId, url };
+        return this.http.send({
+            method: 'POST',
+            path: '/media',
+            body: { kind: 'json', value },
+            idempotencyKey,
+        });
+    }
+    mediaList(filters) {
+        return this.http.send({ method: 'GET', path: '/media', query: filters });
+    }
+    getMedia(id) {
+        return this.http.send({ method: 'GET', path: (0, path_of_1.pathOf)('media', id) });
+    }
+    async deleteMedia(id) {
+        await this.http.send({ method: 'DELETE', path: (0, path_of_1.pathOf)('media', id) });
+    }
+    createWebhook(input) {
+        return this.http.send({
+            method: 'POST',
+            path: '/webhooks',
+            body: { kind: 'json', value: input },
+        });
+    }
+    async webhooks() {
+        return (await this.http.send({ method: 'GET', path: '/webhooks' })).data;
+    }
+    async deleteWebhook(id) {
+        await this.http.send({ method: 'DELETE', path: (0, path_of_1.pathOf)('webhooks', id) });
+    }
+    /** Sends a test delivery, signed like a real one. */
+    testWebhook(id) {
+        return this.http.send({ method: 'POST', path: (0, path_of_1.pathOf)('webhooks', id, 'test') });
+    }
+}
+exports.Sofia = Sofia;

package/src/lib/discovery/discovery.types.d.ts

@@ -0,0 +1,50 @@
+export type Scope = 'establishments:read' | 'accounts:read' | 'accounts:write' | 'media:read' | 'media:write' | 'posts:read' | 'posts:write' | 'insights:read' | 'webhooks:read' | 'webhooks:write' | 'offline_access';
+/** Who the key acts for, and what it may do. */
+export type Me = {
+    readonly tokenType: 'personal_key' | 'authorization_code' | 'client_credentials';
+    readonly application: {
+        readonly id: string;
+        readonly clientId: string;
+        readonly name: string;
+    };
+    readonly user: {
+        readonly id: string;
+    };
+    readonly coverage: 'workspace' | 'account';
+    readonly workspaces: readonly {
+        readonly id: string;
+        readonly name: string;
+    }[];
+    readonly scopes: readonly Scope[];
+    /** `test`: nothing reaches a network. */
+    readonly mode: 'test' | 'live';
+    readonly expiresAt?: string;
+};
+/** A network's rules, the same ones Sofia applies before publishing. */
+export type PlatformRules = {
+    readonly platform: 'instagram' | 'facebook' | 'x' | 'linkedin' | 'tiktok';
+    readonly name: string;
+    readonly available: boolean;
+    readonly caption: {
+        readonly maxLength: number;
+        readonly maxHashtags?: number;
+        readonly maxMentions?: number;
+        readonly enforced: boolean;
+        readonly thread?: {
+            readonly maxPosts: number;
+        };
+    };
+    readonly media: {
+        readonly maxCount: number;
+        readonly enforced: boolean;
+        readonly mixImagesAndVideo: boolean;
+        readonly imageTypes: readonly string[];
+        readonly videoTypes: readonly string[];
+    };
+    readonly formats: readonly {
+        readonly format: string;
+        readonly default: boolean;
+        readonly requiredMedia: 'none' | 'image' | 'video' | 'any';
+        readonly captionPublished: boolean;
+    }[];
+};

package/src/lib/discovery/discovery.types.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/src/lib/establishments/establishment.types.d.ts

@@ -0,0 +1,71 @@
+import type { Platform } from '../posts/post.types';
+export type Establishment = {
+    readonly id: string;
+    readonly name: string;
+};
+/** A connected social account: Postiz calls it an integration, the Sofia app a network. */
+export type SocialAccount = {
+    readonly id: string;
+    readonly platform: string;
+    readonly handle?: string;
+    readonly name?: string;
+    readonly avatarUrl?: string;
+    readonly status: string;
+};
+export type ConnectionLinkInput = {
+    readonly platform: Platform;
+    /** Where Sofia sends the person back once the account is connected. */
+    readonly redirectUrl?: string;
+};
+/** A page hosted by Sofia where the person connects the account. */
+export type ConnectionLink = {
+    readonly platform: string;
+    readonly url: string;
+    readonly expiresAt: string;
+};
+export type InsightsPeriod = 'last24Hours' | 'last7Days' | 'last28Days';
+export type MetricReading = {
+    readonly status: 'available' | 'unavailable';
+    readonly value?: number;
+    readonly reason?: string;
+    readonly mayBeDelayed?: boolean;
+    readonly sourceMetric?: string;
+    readonly granularity?: 'lifetime' | 'hour' | 'day' | 'period' | 'video-second';
+};
+export type NetworkInsights = {
+    readonly platform: string;
+    readonly socialAccountId: string;
+    readonly views: MetricReading;
+    readonly reach: MetricReading;
+    readonly reachDeltaPercent: MetricReading;
+    readonly accountsEngaged: MetricReading;
+    readonly totalInteractions: MetricReading;
+    readonly likes: MetricReading;
+    readonly comments: MetricReading;
+    readonly shares: MetricReading;
+    readonly saves: MetricReading;
+    readonly engagementRatePercent: MetricReading;
+    readonly engagementDeltaPoints: MetricReading;
+    readonly followersDelta: MetricReading;
+    readonly postsPublishedDuringPeriod: MetricReading;
+    readonly followersTotal: MetricReading;
+    readonly postsTotal: MetricReading;
+    readonly reachDailySeries?: readonly number[];
+    readonly engagementDailySeries?: readonly number[];
+    readonly followersDailySeries?: readonly number[];
+    readonly hasInsightsData: boolean;
+    readonly mayBeDelayed: boolean;
+    readonly fetchedAt?: number;
+    readonly collection: {
+        readonly state: 'collected' | 'awaiting-first-collection';
+        readonly collectedAt?: number;
+        readonly isOutdated: boolean;
+        readonly isCollecting: boolean;
+        readonly nextCollectionAt?: number;
+    };
+};
+export type EstablishmentInsights = {
+    readonly establishmentId: string;
+    readonly period: InsightsPeriod;
+    readonly data: readonly NetworkInsights[];
+};

package/src/lib/establishments/establishment.types.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/src/lib/http/api-request.d.ts

@@ -0,0 +1,23 @@
+export type HttpMethod = 'GET' | 'POST' | 'PATCH' | 'DELETE';
+export type QueryValue = string | number | boolean | Date | undefined;
+export type MultipartBody = {
+    readonly kind: 'multipart';
+    readonly fields: Readonly<Record<string, string>>;
+    readonly file: {
+        readonly field: string;
+        readonly name: string;
+        readonly blob: Blob;
+    };
+};
+export type JsonBody = {
+    readonly kind: 'json';
+    readonly value: unknown;
+};
+/** A call to Sofia API v1: `path` is relative to `/api/v1`. */
+export type ApiRequest = {
+    readonly method: HttpMethod;
+    readonly path: string;
+    readonly query?: Readonly<Record<string, QueryValue>>;
+    readonly body?: JsonBody | MultipartBody;
+    readonly idempotencyKey?: string;
+};

package/src/lib/http/api-request.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/src/lib/http/content-type.d.ts

@@ -0,0 +1,2 @@
+/** The content type a file name implies; the API reads the bytes and refuses what it does not take. */
+export declare const contentTypeOf: (fileName: string) => string;

package/src/lib/http/content-type.js

@@ -0,0 +1,20 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.contentTypeOf = void 0;
+const CONTENT_TYPE_OF_EXTENSION = {
+    jpg: 'image/jpeg',
+    jpeg: 'image/jpeg',
+    png: 'image/png',
+    gif: 'image/gif',
+    webp: 'image/webp',
+    heic: 'image/heic',
+    mp4: 'video/mp4',
+    mov: 'video/quicktime',
+    webm: 'video/webm',
+};
+/** The content type a file name implies; the API reads the bytes and refuses what it does not take. */
+const contentTypeOf = (fileName) => {
+    const extension = fileName.split('.').pop()?.toLowerCase() ?? '';
+    return CONTENT_TYPE_OF_EXTENSION[extension] ?? 'application/octet-stream';
+};
+exports.contentTypeOf = contentTypeOf;

package/src/lib/http/error-from-response.d.ts

@@ -0,0 +1,9 @@
+import { SofiaApiError } from './sofia-api-error';
+/** `Retry-After` in seconds; an HTTP date is turned into the seconds left until it. */
+export declare const retryAfterSecondsOf: (header: string | undefined, now: Date) => number | undefined;
+/**
+ * Reads both error shapes of Sofia API: the `{ error: { code, message, details? } }` envelope
+ * and the RFC 6749 `{ error, error_description }` of the token endpoint. Anything else is
+ * `http_<status>`: a proxy page, an empty body.
+ */
+export declare const errorFromResponse: (status: number, body: unknown, retryAfterSeconds: number | undefined) => SofiaApiError;

package/src/lib/http/error-from-response.js

@@ -0,0 +1,43 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.errorFromResponse = exports.retryAfterSecondsOf = void 0;
+const sofia_api_error_1 = require("./sofia-api-error");
+const asFields = (value) => typeof value === 'object' && value ? value : {};
+const textOf = (value) => typeof value === 'string' ? value : undefined;
+const detailsOf = (value) => Array.isArray(value)
+    ? value.filter((detail) => textOf(asFields(detail)['code']) !== undefined)
+    : [];
+/** `Retry-After` in seconds; an HTTP date is turned into the seconds left until it. */
+const retryAfterSecondsOf = (header, now) => {
+    if (header === undefined || header.trim() === '')
+        return undefined;
+    const seconds = Number(header);
+    if (Number.isFinite(seconds))
+        return Math.max(0, Math.ceil(seconds));
+    const at = Date.parse(header);
+    return Number.isNaN(at) ? undefined : Math.max(0, Math.ceil((at - now.getTime()) / 1000));
+};
+exports.retryAfterSecondsOf = retryAfterSecondsOf;
+/**
+ * Reads both error shapes of Sofia API: the `{ error: { code, message, details? } }` envelope
+ * and the RFC 6749 `{ error, error_description }` of the token endpoint. Anything else is
+ * `http_<status>`: a proxy page, an empty body.
+ */
+const errorFromResponse = (status, body, retryAfterSeconds) => {
+    const fields = asFields(body);
+    const envelope = asFields(fields['error']);
+    const code = textOf(envelope['code']) ?? textOf(fields['error']) ?? `http_${status}`;
+    const message = textOf(envelope['message']) ??
+        textOf(fields['error_description']) ??
+        `Sofia API answered ${status}.`;
+    return new sofia_api_error_1.SofiaApiError({
+        status,
+        code,
+        message,
+        details: detailsOf(envelope['details']),
+        docUrl: textOf(envelope['docUrl']),
+        requestId: textOf(envelope['requestId']),
+        retryAfterSeconds,
+    });
+};
+exports.errorFromResponse = errorFromResponse;

package/src/lib/http/path-of.d.ts

@@ -0,0 +1,2 @@
+/** `/posts/<id>`: every identifier is encoded, so an id never reaches another route. */
+export declare const pathOf: (...segments: readonly string[]) => string;

package/src/lib/http/path-of.js

@@ -0,0 +1,6 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.pathOf = void 0;
+/** `/posts/<id>`: every identifier is encoded, so an id never reaches another route. */
+const pathOf = (...segments) => segments.map((segment) => `/${encodeURIComponent(segment)}`).join('');
+exports.pathOf = pathOf;

package/src/lib/http/sdk-version.d.ts

@@ -0,0 +1,2 @@
+/** Kept equal to `version` in the package.json by a spec: tsc does not ship a JSON import. */
+export declare const SDK_VERSION = "0.1.0";

package/src/lib/http/sdk-version.js

@@ -0,0 +1,5 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SDK_VERSION = void 0;
+/** Kept equal to `version` in the package.json by a spec: tsc does not ship a JSON import. */
+exports.SDK_VERSION = '0.1.0';

package/src/lib/http/sofia-api-error.d.ts

@@ -0,0 +1,33 @@
+/** One reason of a refusal: a field of a malformed request, or a network rule a post breaks. */
+export type SofiaApiErrorDetail = {
+    readonly code: string;
+    readonly field?: string;
+    readonly platform?: string;
+    readonly message?: string;
+    readonly max?: number;
+    readonly actual?: number;
+};
+export type SofiaApiErrorInit = {
+    readonly status: number;
+    readonly code: string;
+    readonly message: string;
+    readonly details?: readonly SofiaApiErrorDetail[];
+    readonly docUrl?: string;
+    readonly requestId?: string;
+    readonly retryAfterSeconds?: number;
+};
+/**
+ * Every failure of a call: the error envelope of Sofia API (ADR 0612), or `network_error` with
+ * status 0 when the API could not be reached. `code` is stable, `message` is for people.
+ */
+export declare class SofiaApiError extends Error {
+    readonly status: number;
+    readonly code: string;
+    readonly details: readonly SofiaApiErrorDetail[];
+    /** Absent on the RFC 6749 errors of the token endpoint, and on `network_error`. */
+    readonly docUrl?: string;
+    readonly requestId?: string;
+    /** Set on 429 and 503: how long to wait before trying again. */
+    readonly retryAfterSeconds?: number;
+    constructor(init: SofiaApiErrorInit);
+}

package/src/lib/http/sofia-api-error.js

@@ -0,0 +1,20 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SofiaApiError = void 0;
+/**
+ * Every failure of a call: the error envelope of Sofia API (ADR 0612), or `network_error` with
+ * status 0 when the API could not be reached. `code` is stable, `message` is for people.
+ */
+class SofiaApiError extends Error {
+    constructor(init) {
+        super(init.message);
+        this.name = 'SofiaApiError';
+        this.status = init.status;
+        this.code = init.code;
+        this.details = init.details ?? [];
+        this.docUrl = init.docUrl;
+        this.requestId = init.requestId;
+        this.retryAfterSeconds = init.retryAfterSeconds;
+    }
+}
+exports.SofiaApiError = SofiaApiError;

package/src/lib/http/sofia-http-client.d.ts

@@ -0,0 +1,16 @@
+import type { ApiRequest } from './api-request';
+export type SofiaHttpClientOptions = {
+    readonly apiKey: string;
+    readonly baseUrl: string;
+    readonly userAgent: string;
+    readonly fetch: typeof fetch;
+};
+/** Sends one request to `<baseUrl>/api/v1`, and turns any non-2xx answer into a `SofiaApiError`. */
+export declare class SofiaHttpClient {
+    private readonly options;
+    constructor(options: SofiaHttpClientOptions);
+    send<T>(request: ApiRequest): Promise<T>;
+    private dispatch;
+    private urlOf;
+    private headersOf;
+}

package/src/lib/http/sofia-http-client.js

@@ -0,0 +1,78 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SofiaHttpClient = void 0;
+const error_from_response_1 = require("./error-from-response");
+const sofia_api_error_1 = require("./sofia-api-error");
+const queryText = (value) => value instanceof Date ? value.toISOString() : String(value);
+const bodyOf = (body) => {
+    if (body === undefined)
+        return undefined;
+    if (body.kind === 'json')
+        return JSON.stringify(body.value);
+    const form = new FormData();
+    Object.entries(body.fields).forEach(([name, value]) => form.append(name, value));
+    form.append(body.file.field, body.file.blob, body.file.name);
+    return form;
+};
+const readBody = async (response) => {
+    const text = await response.text();
+    if (text === '')
+        return undefined;
+    try {
+        return JSON.parse(text);
+    }
+    catch {
+        return text;
+    }
+};
+/** Sends one request to `<baseUrl>/api/v1`, and turns any non-2xx answer into a `SofiaApiError`. */
+class SofiaHttpClient {
+    constructor(options) {
+        this.options = options;
+    }
+    async send(request) {
+        const response = await this.dispatch(request);
+        const body = await readBody(response);
+        if (!response.ok) {
+            const retryAfter = (0, error_from_response_1.retryAfterSecondsOf)(response.headers.get('retry-after') ?? undefined, new Date());
+            throw (0, error_from_response_1.errorFromResponse)(response.status, body, retryAfter);
+        }
+        return body;
+    }
+    async dispatch(request) {
+        try {
+            return await this.options.fetch(this.urlOf(request), {
+                method: request.method,
+                headers: this.headersOf(request),
+                body: bodyOf(request.body),
+            });
+        }
+        catch (error) {
+            throw new sofia_api_error_1.SofiaApiError({
+                status: 0,
+                code: 'network_error',
+                message: `Could not reach ${this.options.baseUrl}: ${error instanceof Error ? error.message : String(error)}`,
+            });
+        }
+    }
+    urlOf(request) {
+        const url = new URL(`${this.options.baseUrl}/api/v1${request.path}`);
+        Object.entries(request.query ?? {}).forEach(([name, value]) => {
+            if (value !== undefined)
+                url.searchParams.set(name, queryText(value));
+        });
+        return url.toString();
+    }
+    headersOf(request) {
+        return {
+            Authorization: `Bearer ${this.options.apiKey}`,
+            Accept: 'application/json',
+            'User-Agent': this.options.userAgent,
+            ...(request.body?.kind === 'json' ? { 'Content-Type': 'application/json' } : {}),
+            ...(request.idempotencyKey === undefined
+                ? {}
+                : { 'Idempotency-Key': request.idempotencyKey }),
+        };
+    }
+}
+exports.SofiaHttpClient = SofiaHttpClient;

package/src/lib/media/media.types.d.ts

@@ -0,0 +1,34 @@
+export type MediaType = 'image' | 'video';
+export type Media = {
+    readonly id: string;
+    readonly type: MediaType;
+    readonly url: string;
+};
+export type MediaListItem = Media & {
+    readonly fileName: string;
+    readonly contentType: string;
+    readonly size: number;
+    readonly createdAt: string;
+    readonly thumbnailUrl?: string;
+};
+/** A file's bytes: a `Buffer` read from disk, any `Uint8Array`, or a `Blob`. */
+export type UploadableFile = Uint8Array | Blob;
+export type UploadInput = {
+    readonly establishmentId: string;
+    readonly file: UploadableFile;
+    /** Its extension gives the content type when `contentType` is absent: `photo.jpg`, `clip.mp4`. */
+    readonly fileName: string;
+    readonly contentType?: string;
+    readonly idempotencyKey?: string;
+};
+export type UploadFromUrlInput = {
+    readonly establishmentId: string;
+    /** A public URL Sofia downloads itself. */
+    readonly url: string;
+    readonly idempotencyKey?: string;
+};
+export type ListMediaFilters = {
+    readonly establishmentId: string;
+    readonly cursor?: string;
+    readonly limit?: number;
+};

package/src/lib/media/media.types.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/src/lib/posts/post.types.d.ts

@@ -0,0 +1,109 @@
+/** The networks Sofia API v1 publishes to. */
+export type Platform = 'instagram' | 'facebook' | 'x' | 'linkedin' | 'tiktok';
+/** An instant, as an ISO 8601 string or a `Date` (sent as its ISO string). */
+export type Instant = string | Date;
+export type PostMedia = {
+    /** A media of the library, returned by `upload` or `uploadFromUrl`. */
+    readonly id?: string;
+    /** A public URL Sofia fetches itself. */
+    readonly url?: string;
+    readonly type?: 'image' | 'video';
+};
+/** One network of a post: each network gets its own text, media and format. */
+export type PostTarget = {
+    readonly platform: Platform;
+    readonly text: string;
+    readonly media?: readonly PostMedia[];
+    /** A format listed by `platforms()`, such as `reel` or `story`; the network's default otherwise. */
+    readonly format?: string;
+    /** Needed only when the establishment has several accounts on this network. */
+    readonly accountId?: string;
+};
+export type PublishPostInput = {
+    readonly establishmentId: string;
+    readonly targets: readonly PostTarget[];
+    /** Absent: published now. In the future: scheduled. */
+    readonly scheduledAt?: Instant;
+    /** `draft`: saved, neither scheduled nor published. */
+    readonly status?: 'draft';
+};
+export type PublishPostOptions = {
+    /** Checks everything sending would check, writes nothing. */
+    readonly dryRun?: boolean;
+    /** Replayed with the same body, the request answers the same post instead of a second one. */
+    readonly idempotencyKey?: string;
+};
+export type EditPostInput = {
+    readonly targets?: readonly PostTarget[];
+    readonly scheduledAt?: Instant;
+    readonly status?: 'draft' | 'scheduled';
+};
+export type TargetState = 'draft' | 'scheduled' | 'publishing' | 'published' | 'sent_to_inbox' | 'failed';
+export type LivePostTarget = {
+    readonly platform: string;
+    readonly accountId: string;
+    readonly state: TargetState;
+    readonly publishedAt?: string;
+    readonly permalink?: string;
+    readonly error?: string;
+};
+export type LivePost = {
+    readonly id: string;
+    /** The synthesis of the networks' states: `partial` when one failed and another went out. */
+    readonly status: TargetState | 'partial';
+    readonly establishmentId: string;
+    readonly scheduledAt?: string;
+    readonly createdAt: string;
+    readonly targets: readonly LivePostTarget[];
+};
+/** What a test key answers: nothing reaches a network. */
+export type SandboxPost = {
+    readonly id: string;
+    readonly status: 'simulated';
+    readonly scheduledAt?: string;
+    readonly targets: readonly {
+        readonly platform: string;
+        readonly accountId?: string;
+        readonly state: 'simulated';
+    }[];
+};
+export type CreatedLivePost = {
+    readonly id: string;
+    readonly status: 'draft' | 'publishing' | 'scheduled';
+    readonly establishmentId: string;
+    readonly scheduledAt?: string;
+    readonly targets: readonly {
+        readonly platform: string;
+        readonly accountId: string;
+        readonly state: 'draft' | 'publishing' | 'scheduled' | 'failed';
+    }[];
+};
+/** What a dry run answers when the post would be accepted. */
+export type CheckedPost = {
+    readonly status: 'ready';
+    readonly dryRun: true;
+    readonly targets: readonly {
+        readonly platform: string;
+        readonly accountId?: string;
+        readonly handle?: string;
+        readonly state: 'ready';
+    }[];
+};
+export type Post = LivePost | SandboxPost;
+export type PublishedPost = CreatedLivePost | SandboxPost | CheckedPost;
+export type ListPostsFilters = {
+    readonly establishmentId?: string;
+    readonly cursor?: string;
+    readonly status?: TargetState;
+    readonly from?: Instant;
+    readonly to?: Instant;
+    /** `me`: the person the key acts for; `app`: the posts this application created. */
+    readonly createdBy?: 'me' | 'app';
+    /** 1 to 100, 20 by default. */
+    readonly limit?: number;
+};
+export type Page<Item> = {
+    readonly data: readonly Item[];
+    /** Absent on the last page. */
+    readonly nextCursor?: string;
+};

package/src/lib/posts/post.types.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/src/lib/webhooks/webhook.types.d.ts

@@ -0,0 +1,19 @@
+export type WebhookEvent = 'post.published' | 'post.failed';
+export type RegisterWebhookInput = {
+    /** An HTTPS URL that answers 2xx. */
+    readonly url: string;
+    readonly events: readonly WebhookEvent[];
+};
+export type Webhook = {
+    readonly id: string;
+    readonly url: string;
+    readonly events: readonly WebhookEvent[];
+    readonly createdAt: string;
+};
+/** The secret signs every delivery; it is shown only once, here. */
+export type CreatedWebhook = Webhook & {
+    readonly secret: string;
+};
+export type WebhookTest = {
+    readonly deliveryId: string;
+};

package/src/lib/webhooks/webhook.types.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });