@xtellig/autosocializer 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Xtellig
+
+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

@@ -0,0 +1,163 @@
+# @xtellig/autosocializer
+
+Official SDK for the [**Autosocializer**](https://www.autosocializer.com) platform, by [Xtellig](https://www.xtellig.com).
+
+Create SeamlessBoard records via GraphQL with a small, typed client — including multipart file attachments.
+
+> MIT licensed · Node.js ≥ 18
+
+---
+
+## Install
+
+```bash
+npm install @xtellig/autosocializer
+```
+
+---
+
+## Quick start
+
+```ts
+import { SeamlessBoardApi } from "@xtellig/autosocializer";
+
+const api = new SeamlessBoardApi({
+  url: "https://xtellig.autosocializer.com/api/graphql-endpoint",
+  apiKey: "TOKEN",
+});
+
+const res = await api.addRecord({
+  section: "67a448a8c78d6c21598d67d5",
+  data: {
+    priority_select_jlaFEbose: "High",
+    gender_select_BgSd_OMKS: "Male",
+    marks_number_4LbncDrii: 83,
+    number_field_number_s6ECxMbr3: 74,
+    email_email_GOv6dM7VF: "Theodora.Pacocha14@xtellig.com",
+    due_date_date_g8DAgJjta: "2025-12-28T22:16:48.102Z",
+  },
+});
+
+console.log(res._id);
+```
+
+---
+
+## Attachments / file fields
+
+Attachment fields cannot be sent as plain JSON. Wrap file bytes with `file()` — the client switches to GraphQL multipart FormData automatically.
+
+Content-type is optional. When omitted, it is inferred from the filename (fallback: `application/octet-stream`).
+
+```ts
+import { readFileSync } from "node:fs";
+import { SeamlessBoardApi, file } from "@xtellig/autosocializer";
+
+const api = new SeamlessBoardApi({
+  url: "https://xtellig.autosocializer.com/api/graphql-endpoint",
+  apiKey: "TOKEN",
+});
+
+const resume = file(readFileSync("./cv.pdf"), "cv.pdf");
+// or with an explicit MIME type:
+// const resume = file(buffer, "cv.pdf", "application/pdf");
+
+const res = await api.addRecord({
+  section: "67a448a8c78d6c21598d67d5",
+  data: {
+    email_email_GOv6dM7VF: "user@example.com",
+    resume_attachment_FIELD_ID: resume,
+    // multiple files on one field:
+    // documents_attachment_FIELD_ID: [file(buf1, "a.pdf"), file(buf2, "b.png")],
+  },
+});
+```
+
+`file()` accepts `Buffer`, `Uint8Array`, `ArrayBuffer`, or `Blob`.
+
+---
+
+## Server-only (this release)
+
+`SeamlessBoardApi.addRecord` is **blocked in the browser**. Call it from Node.js (or another server runtime). If invoked in a browser it throws `BrowserEnvironmentError`.
+
+Future package features may be browser-allowed; the environment guard is applied **per feature**, not globally.
+
+---
+
+## API reference
+
+### `new SeamlessBoardApi(config)`
+
+| Param           | Type     | Description                              |
+| --------------- | -------- | ---------------------------------------- |
+| `config.url`    | `string` | GraphQL endpoint URL                     |
+| `config.apiKey` | `string` | Access token (`Authorization: Bearer …`) |
+
+### `api.addRecord(input)`
+
+| Param           | Type         | Description                    |
+| --------------- | ------------ | ------------------------------ |
+| `input.section` | `string`     | Board section ID               |
+| `input.data`    | `RecordData` | Field values keyed by field ID |
+
+**Returns:** `Promise<{ _id: string; no: number; }>`
+
+### `file(content, filename, contentType?)`
+
+Marks binary content as an attachment for multipart upload.
+
+### Errors
+
+| Class                     | When                                         |
+| ------------------------- | -------------------------------------------- |
+| `ApiError`                | HTTP or GraphQL failure (`status`, `errors`) |
+| `BrowserEnvironmentError` | Server-only feature called in a browser      |
+| `AutosocializerError`     | Base class for the above                     |
+
+```ts
+import { SeamlessBoardApi, ApiError } from "@xtellig/autosocializer";
+
+try {
+  await api.addRecord({
+    section: "…",
+    data: {
+      /* … */
+    },
+  });
+} catch (err) {
+  if (err instanceof ApiError) {
+    console.error(err.status, err.errors);
+  } else {
+    throw err;
+  }
+}
+```
+
+### TypeScript types
+
+All types are exported for use in your own code:
+
+| Type                     | Description                                   |
+| ------------------------ | --------------------------------------------- |
+| `SeamlessBoardApiConfig` | Constructor config (`url`, `apiKey`)          |
+| `AddRecordInput`         | `{ section, data }` passed to `addRecord`     |
+| `AddRecordResult`        | `{ _id }` returned by `addRecord`             |
+| `RecordData`             | Field values keyed by field ID                |
+| `RecordValue`            | A scalar, one `FileUpload`, or `FileUpload[]` |
+| `ScalarValue`            | `string \| number \| boolean \| null`         |
+| `FileUpload`             | Marker returned by `file()`                   |
+| `FileContent`            | Accepted input for `file()` content           |
+
+---
+
+## Requirements
+
+- Node.js **≥ 18** (uses global `fetch`, `FormData`, `Blob`)
+- A valid Autosocializer **Access Token**
+
+---
+
+## License
+
+[MIT](./LICENSE) © Xtellig

package/dist/index.cjs

@@ -0,0 +1,346 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/index.ts
+var index_exports = {};
+__export(index_exports, {
+  ApiError: () => ApiError,
+  AutosocializerError: () => AutosocializerError,
+  BrowserEnvironmentError: () => BrowserEnvironmentError,
+  FileUpload: () => FileUpload,
+  SeamlessBoardApi: () => SeamlessBoardApi,
+  file: () => file
+});
+module.exports = __toCommonJS(index_exports);
+
+// src/errors.ts
+var AutosocializerError = class extends Error {
+  constructor(message) {
+    super(message);
+    this.name = "AutosocializerError";
+  }
+};
+var ApiError = class extends AutosocializerError {
+  /** HTTP status code when available. */
+  status;
+  /** Raw GraphQL error payload when available. */
+  errors;
+  constructor(message, options) {
+    super(message);
+    this.name = "ApiError";
+    this.status = options?.status;
+    this.errors = options?.errors;
+  }
+};
+var BrowserEnvironmentError = class extends AutosocializerError {
+  /** Feature name that was blocked (e.g. "SeamlessBoardApi.addRecord"). */
+  feature;
+  constructor(feature) {
+    super(
+      `${feature} is only available in a server environment (Node.js). It cannot run in the browser. Call it from your backend instead.`
+    );
+    this.name = "BrowserEnvironmentError";
+    this.feature = feature;
+  }
+};
+
+// src/env/guard.ts
+function isBrowserEnvironment() {
+  return typeof globalThis !== "undefined" && typeof globalThis.window !== "undefined" && typeof globalThis.document !== "undefined";
+}
+function assertServerEnvironment(feature) {
+  if (isBrowserEnvironment()) {
+    throw new BrowserEnvironmentError(feature);
+  }
+}
+
+// src/graphql/mutation.ts
+var ADD_RECORD_MUTATION = `
+  mutation addSeamlessBoardRecord($createRecordViaApiInput: CreateRecordViaApiInput!) {
+    addSeamlessBoardRecord(createRecordViaApiInput: $createRecordViaApiInput) {
+      _id
+      no
+    }
+  }
+`.trim();
+var ADD_RECORD_OPERATION_NAME = "addSeamlessBoardRecord";
+
+// src/attachments/mime.ts
+var MIME_BY_EXT = {
+  // Documents
+  pdf: "application/pdf",
+  doc: "application/msword",
+  docx: "application/vnd.openxmlformats-officedocument.wordprocessingml.document",
+  xls: "application/vnd.ms-excel",
+  xlsx: "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet",
+  ppt: "application/vnd.ms-powerpoint",
+  pptx: "application/vnd.openxmlformats-officedocument.presentationml.presentation",
+  txt: "text/plain",
+  csv: "text/csv",
+  json: "application/json",
+  xml: "application/xml",
+  // Images
+  png: "image/png",
+  jpg: "image/jpeg",
+  jpeg: "image/jpeg",
+  gif: "image/gif",
+  webp: "image/webp",
+  svg: "image/svg+xml",
+  ico: "image/x-icon",
+  bmp: "image/bmp",
+  // Audio / video
+  mp3: "audio/mpeg",
+  wav: "audio/wav",
+  ogg: "audio/ogg",
+  mp4: "video/mp4",
+  webm: "video/webm",
+  // Archives
+  zip: "application/zip",
+  rar: "application/vnd.rar",
+  "7z": "application/x-7z-compressed",
+  gz: "application/gzip",
+  tar: "application/x-tar"
+};
+function resolveMime(filename, contentType) {
+  if (contentType && contentType.trim()) {
+    return contentType.trim();
+  }
+  const ext = filename.split(".").pop()?.toLowerCase() ?? "";
+  return MIME_BY_EXT[ext] ?? "application/octet-stream";
+}
+
+// src/attachments/file.ts
+var FileUpload = class {
+  content;
+  filename;
+  contentType;
+  /** @internal */
+  constructor(content, filename, contentType) {
+    this.content = content;
+    this.filename = filename;
+    this.contentType = contentType;
+  }
+};
+function file(content, filename, contentType) {
+  return new FileUpload(content, filename, resolveMime(filename, contentType));
+}
+function isFileUpload(value) {
+  return value instanceof FileUpload;
+}
+
+// src/graphql/multipart.ts
+function dummyKey() {
+  return `dummy-${Math.random().toString(36).substring(2, 10)}`;
+}
+function toBlob(upload) {
+  if (upload.content instanceof Blob) {
+    return upload.content.type ? upload.content : new Blob([upload.content], { type: upload.contentType });
+  }
+  return new Blob([upload.content], {
+    type: upload.contentType
+  });
+}
+function transformField(value, fieldId, parts) {
+  if (isFileUpload(value)) {
+    const key = dummyKey();
+    parts.push({
+      key: String(parts.length + 1),
+      path: `variables.createRecordViaApiInput.data.${fieldId}.${key}`,
+      upload: value
+    });
+    return { [key]: null };
+  }
+  if (Array.isArray(value) && value.some(isFileUpload)) {
+    const obj = {};
+    for (const item of value) {
+      if (!isFileUpload(item)) continue;
+      const key = dummyKey();
+      parts.push({
+        key: String(parts.length + 1),
+        path: `variables.createRecordViaApiInput.data.${fieldId}.${key}`,
+        upload: item
+      });
+      obj[key] = null;
+    }
+    return obj;
+  }
+  return value;
+}
+function hasFileUploads(data) {
+  for (const value of Object.values(data)) {
+    if (isFileUpload(value)) return true;
+    if (Array.isArray(value) && value.some(isFileUpload)) return true;
+  }
+  return false;
+}
+function buildMultipartFormData(section, data) {
+  const parts = [];
+  const transformed = {};
+  for (const [fieldId, value] of Object.entries(data)) {
+    transformed[fieldId] = transformField(value, fieldId, parts);
+  }
+  const operations = {
+    query: ADD_RECORD_MUTATION,
+    variables: {
+      createRecordViaApiInput: {
+        section,
+        data: transformed
+      }
+    }
+  };
+  const map = {};
+  for (const part of parts) {
+    map[part.key] = [part.path];
+  }
+  const formData = new FormData();
+  formData.append("operations", JSON.stringify(operations));
+  formData.append("map", JSON.stringify(map));
+  for (const part of parts) {
+    formData.append(part.key, toBlob(part.upload), part.upload.filename);
+  }
+  return { formData, hasAttachments: parts.length > 0 };
+}
+
+// src/http/request.ts
+async function graphqlRequest(options) {
+  const headers = {
+    Authorization: `Bearer ${options.apiKey}`,
+    "x-apollo-operation-name": options.operationName,
+    ...options.headers
+  };
+  if (typeof options.body === "string") {
+    headers["Content-Type"] = "application/json";
+  }
+  const response = await fetch(options.url, {
+    method: "POST",
+    headers,
+    body: options.body
+  });
+  let payload;
+  const text = await response.text();
+  try {
+    payload = text ? JSON.parse(text) : void 0;
+  } catch {
+    throw new ApiError(
+      `Invalid JSON response from GraphQL endpoint (HTTP ${response.status}).`,
+      { status: response.status }
+    );
+  }
+  if (!response.ok) {
+    const message = payload?.errors?.map((e) => e.message).filter(Boolean).join("; ") || `GraphQL request failed with HTTP ${response.status}.`;
+    throw new ApiError(message, {
+      status: response.status,
+      errors: payload?.errors
+    });
+  }
+  if (payload?.errors?.length) {
+    const message = payload.errors.map((e) => e.message).filter(Boolean).join("; ") || "GraphQL request returned errors.";
+    throw new ApiError(message, {
+      status: response.status,
+      errors: payload.errors
+    });
+  }
+  if (!payload?.data) {
+    throw new ApiError("GraphQL response contained no data.", {
+      status: response.status
+    });
+  }
+  return payload.data;
+}
+
+// src/client/SeamlessBoardApi.ts
+var SeamlessBoardApi = class {
+  url;
+  apiKey;
+  /**
+   * @param config - GraphQL endpoint URL and access token.
+   */
+  constructor(config) {
+    if (!config?.url) {
+      throw new Error("SeamlessBoardApi: `url` is required.");
+    }
+    if (!config?.apiKey) {
+      throw new Error("SeamlessBoardApi: `apiKey` is required.");
+    }
+    this.url = config.url;
+    this.apiKey = config.apiKey;
+  }
+  /**
+   * Create a record for the given section.
+   *
+   * - Plain JSON fields → JSON POST.
+   * - Attachment fields (via {@link file}) → GraphQL multipart FormData POST.
+   *
+   * **Server-only:** throws {@link BrowserEnvironmentError} in the browser.
+   *
+   * @param input - Section ID and field data matching the board schema.
+   * @returns The created record `{ _id, no }`.
+   */
+  async addRecord(input) {
+    assertServerEnvironment("SeamlessBoardApi.addRecord");
+    if (!input?.section) {
+      throw new Error("addRecord: `section` is required.");
+    }
+    if (!input?.data || typeof input.data !== "object") {
+      throw new Error("addRecord: `data` is required.");
+    }
+    if (hasFileUploads(input.data)) {
+      return this.addRecordWithAttachments(input);
+    }
+    return this.addRecordJson(input);
+  }
+  /** JSON POST path (no attachments). */
+  async addRecordJson(input) {
+    const data = await graphqlRequest({
+      url: this.url,
+      apiKey: this.apiKey,
+      operationName: ADD_RECORD_OPERATION_NAME,
+      body: JSON.stringify({
+        query: ADD_RECORD_MUTATION,
+        variables: {
+          createRecordViaApiInput: {
+            section: input.section,
+            data: input.data
+          }
+        }
+      })
+    });
+    return data.addSeamlessBoardRecord;
+  }
+  /** Multipart POST path (one or more attachment fields). */
+  async addRecordWithAttachments(input) {
+    const { formData } = buildMultipartFormData(input.section, input.data);
+    const data = await graphqlRequest({
+      url: this.url,
+      apiKey: this.apiKey,
+      operationName: ADD_RECORD_OPERATION_NAME,
+      body: formData
+    });
+    return data.addSeamlessBoardRecord;
+  }
+};
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  ApiError,
+  AutosocializerError,
+  BrowserEnvironmentError,
+  FileUpload,
+  SeamlessBoardApi,
+  file
+});

package/dist/index.d.cts

@@ -0,0 +1,159 @@
+/** Binary content accepted by {@link file}. */
+type FileContent = Buffer | Uint8Array | ArrayBuffer | Blob;
+/**
+ * Opaque wrapper marking a value as a file attachment for multipart upload.
+ * Create instances via {@link file} — do not construct this class directly.
+ */
+declare class FileUpload {
+    readonly content: FileContent;
+    readonly filename: string;
+    readonly contentType: string;
+    /** @internal */
+    constructor(content: FileContent, filename: string, contentType: string);
+}
+/**
+ * Mark a binary value as a board attachment field.
+ * Content-type is optional — when omitted it is inferred from the filename.
+ *
+ * @param content - File bytes (`Buffer`, `Uint8Array`, `ArrayBuffer`, or `Blob`).
+ * @param filename - Original filename (used for MIME detection and upload name).
+ * @param contentType - Optional MIME override (e.g. `"application/pdf"`).
+ *
+ * @example
+ * ```ts
+ * import { readFileSync } from "node:fs";
+ * import { file } from "@xtellig/autosocializer";
+ *
+ * const resume = file(readFileSync("./cv.pdf"), "cv.pdf");
+ * // or with an explicit type:
+ * const resume = file(buffer, "cv.pdf", "application/pdf");
+ * ```
+ */
+declare function file(content: FileContent, filename: string, contentType?: string): FileUpload;
+
+/**
+ * Configuration for {@link SeamlessBoardApi}.
+ */
+interface SeamlessBoardApiConfig {
+    /**
+     * GraphQL endpoint URL.
+     * @example "https://xtellig.autosocializer.com/api/graphql-endpoint"
+     */
+    url: string;
+    /**
+     * Access token sent as `Authorization: Bearer <apiKey>`.
+     */
+    apiKey: string;
+}
+/**
+ * Scalar values accepted for non-attachment board fields.
+ */
+type ScalarValue = string | number | boolean | null;
+/**
+ * A single field value: a scalar, one file upload, or multiple file uploads.
+ */
+type RecordValue = ScalarValue | FileUpload | FileUpload[];
+/**
+ * Board field data keyed by field ID (e.g. `marks_number_4LbncDrii`).
+ */
+type RecordData = Record<string, RecordValue>;
+/**
+ * Input for {@link SeamlessBoardApi.addRecord}.
+ */
+interface AddRecordInput {
+    /**
+     * Target board section ID.
+     * @example "67a448a8c78d6c21598d67d5"
+     */
+    section: string;
+    /**
+     * Field values keyed by field ID.
+     * Use {@link file} for attachment fields.
+     */
+    data: RecordData;
+}
+/**
+ * Successful response from `addSeamlessBoardRecord`.
+ */
+interface AddRecordResult {
+    /** Created record ID. */
+    _id: string;
+    /** Created record number. */
+    no: number;
+}
+
+/**
+ * Client for Autosocializer SeamlessBoard GraphQL APIs.
+ *
+ * @example
+ * ```ts
+ * import { SeamlessBoardApi } from "@xtellig/autosocializer";
+ *
+ * const api = new SeamlessBoardApi({
+ *   url: "https://xtellig.autosocializer.com/api/graphql-endpoint",
+ *   apiKey: "TOKEN",
+ * });
+ *
+ * const res = await api.addRecord({
+ *   section: "67a448a8c78d6c21598d67d5",
+ *   data: {
+ *     marks_number_4LbncDrii: 83,
+ *     email_email_GOv6dM7VF: "user@example.com",
+ *   },
+ * });
+ * ```
+ */
+declare class SeamlessBoardApi {
+    private readonly url;
+    private readonly apiKey;
+    /**
+     * @param config - GraphQL endpoint URL and access token.
+     */
+    constructor(config: SeamlessBoardApiConfig);
+    /**
+     * Create a record for the given section.
+     *
+     * - Plain JSON fields → JSON POST.
+     * - Attachment fields (via {@link file}) → GraphQL multipart FormData POST.
+     *
+     * **Server-only:** throws {@link BrowserEnvironmentError} in the browser.
+     *
+     * @param input - Section ID and field data matching the board schema.
+     * @returns The created record `{ _id, no }`.
+     */
+    addRecord(input: AddRecordInput): Promise<AddRecordResult>;
+    /** JSON POST path (no attachments). */
+    private addRecordJson;
+    /** Multipart POST path (one or more attachment fields). */
+    private addRecordWithAttachments;
+}
+
+/**
+ * Base error for all @xtellig/autosocializer failures.
+ */
+declare class AutosocializerError extends Error {
+    constructor(message: string);
+}
+/**
+ * Thrown when a GraphQL or HTTP request fails.
+ */
+declare class ApiError extends AutosocializerError {
+    /** HTTP status code when available. */
+    readonly status?: number;
+    /** Raw GraphQL error payload when available. */
+    readonly errors?: unknown[];
+    constructor(message: string, options?: {
+        status?: number;
+        errors?: unknown[];
+    });
+}
+/**
+ * Thrown when a server-only feature is invoked in a browser environment.
+ */
+declare class BrowserEnvironmentError extends AutosocializerError {
+    /** Feature name that was blocked (e.g. "SeamlessBoardApi.addRecord"). */
+    readonly feature: string;
+    constructor(feature: string);
+}
+
+export { type AddRecordInput, type AddRecordResult, ApiError, AutosocializerError, BrowserEnvironmentError, type FileContent, FileUpload, type RecordData, type RecordValue, type ScalarValue, SeamlessBoardApi, type SeamlessBoardApiConfig, file };

package/dist/index.d.ts

@@ -0,0 +1,159 @@
+/** Binary content accepted by {@link file}. */
+type FileContent = Buffer | Uint8Array | ArrayBuffer | Blob;
+/**
+ * Opaque wrapper marking a value as a file attachment for multipart upload.
+ * Create instances via {@link file} — do not construct this class directly.
+ */
+declare class FileUpload {
+    readonly content: FileContent;
+    readonly filename: string;
+    readonly contentType: string;
+    /** @internal */
+    constructor(content: FileContent, filename: string, contentType: string);
+}
+/**
+ * Mark a binary value as a board attachment field.
+ * Content-type is optional — when omitted it is inferred from the filename.
+ *
+ * @param content - File bytes (`Buffer`, `Uint8Array`, `ArrayBuffer`, or `Blob`).
+ * @param filename - Original filename (used for MIME detection and upload name).
+ * @param contentType - Optional MIME override (e.g. `"application/pdf"`).
+ *
+ * @example
+ * ```ts
+ * import { readFileSync } from "node:fs";
+ * import { file } from "@xtellig/autosocializer";
+ *
+ * const resume = file(readFileSync("./cv.pdf"), "cv.pdf");
+ * // or with an explicit type:
+ * const resume = file(buffer, "cv.pdf", "application/pdf");
+ * ```
+ */
+declare function file(content: FileContent, filename: string, contentType?: string): FileUpload;
+
+/**
+ * Configuration for {@link SeamlessBoardApi}.
+ */
+interface SeamlessBoardApiConfig {
+    /**
+     * GraphQL endpoint URL.
+     * @example "https://xtellig.autosocializer.com/api/graphql-endpoint"
+     */
+    url: string;
+    /**
+     * Access token sent as `Authorization: Bearer <apiKey>`.
+     */
+    apiKey: string;
+}
+/**
+ * Scalar values accepted for non-attachment board fields.
+ */
+type ScalarValue = string | number | boolean | null;
+/**
+ * A single field value: a scalar, one file upload, or multiple file uploads.
+ */
+type RecordValue = ScalarValue | FileUpload | FileUpload[];
+/**
+ * Board field data keyed by field ID (e.g. `marks_number_4LbncDrii`).
+ */
+type RecordData = Record<string, RecordValue>;
+/**
+ * Input for {@link SeamlessBoardApi.addRecord}.
+ */
+interface AddRecordInput {
+    /**
+     * Target board section ID.
+     * @example "67a448a8c78d6c21598d67d5"
+     */
+    section: string;
+    /**
+     * Field values keyed by field ID.
+     * Use {@link file} for attachment fields.
+     */
+    data: RecordData;
+}
+/**
+ * Successful response from `addSeamlessBoardRecord`.
+ */
+interface AddRecordResult {
+    /** Created record ID. */
+    _id: string;
+    /** Created record number. */
+    no: number;
+}
+
+/**
+ * Client for Autosocializer SeamlessBoard GraphQL APIs.
+ *
+ * @example
+ * ```ts
+ * import { SeamlessBoardApi } from "@xtellig/autosocializer";
+ *
+ * const api = new SeamlessBoardApi({
+ *   url: "https://xtellig.autosocializer.com/api/graphql-endpoint",
+ *   apiKey: "TOKEN",
+ * });
+ *
+ * const res = await api.addRecord({
+ *   section: "67a448a8c78d6c21598d67d5",
+ *   data: {
+ *     marks_number_4LbncDrii: 83,
+ *     email_email_GOv6dM7VF: "user@example.com",
+ *   },
+ * });
+ * ```
+ */
+declare class SeamlessBoardApi {
+    private readonly url;
+    private readonly apiKey;
+    /**
+     * @param config - GraphQL endpoint URL and access token.
+     */
+    constructor(config: SeamlessBoardApiConfig);
+    /**
+     * Create a record for the given section.
+     *
+     * - Plain JSON fields → JSON POST.
+     * - Attachment fields (via {@link file}) → GraphQL multipart FormData POST.
+     *
+     * **Server-only:** throws {@link BrowserEnvironmentError} in the browser.
+     *
+     * @param input - Section ID and field data matching the board schema.
+     * @returns The created record `{ _id, no }`.
+     */
+    addRecord(input: AddRecordInput): Promise<AddRecordResult>;
+    /** JSON POST path (no attachments). */
+    private addRecordJson;
+    /** Multipart POST path (one or more attachment fields). */
+    private addRecordWithAttachments;
+}
+
+/**
+ * Base error for all @xtellig/autosocializer failures.
+ */
+declare class AutosocializerError extends Error {
+    constructor(message: string);
+}
+/**
+ * Thrown when a GraphQL or HTTP request fails.
+ */
+declare class ApiError extends AutosocializerError {
+    /** HTTP status code when available. */
+    readonly status?: number;
+    /** Raw GraphQL error payload when available. */
+    readonly errors?: unknown[];
+    constructor(message: string, options?: {
+        status?: number;
+        errors?: unknown[];
+    });
+}
+/**
+ * Thrown when a server-only feature is invoked in a browser environment.
+ */
+declare class BrowserEnvironmentError extends AutosocializerError {
+    /** Feature name that was blocked (e.g. "SeamlessBoardApi.addRecord"). */
+    readonly feature: string;
+    constructor(feature: string);
+}
+
+export { type AddRecordInput, type AddRecordResult, ApiError, AutosocializerError, BrowserEnvironmentError, type FileContent, FileUpload, type RecordData, type RecordValue, type ScalarValue, SeamlessBoardApi, type SeamlessBoardApiConfig, file };

package/dist/index.js

@@ -0,0 +1,314 @@
+// src/errors.ts
+var AutosocializerError = class extends Error {
+  constructor(message) {
+    super(message);
+    this.name = "AutosocializerError";
+  }
+};
+var ApiError = class extends AutosocializerError {
+  /** HTTP status code when available. */
+  status;
+  /** Raw GraphQL error payload when available. */
+  errors;
+  constructor(message, options) {
+    super(message);
+    this.name = "ApiError";
+    this.status = options?.status;
+    this.errors = options?.errors;
+  }
+};
+var BrowserEnvironmentError = class extends AutosocializerError {
+  /** Feature name that was blocked (e.g. "SeamlessBoardApi.addRecord"). */
+  feature;
+  constructor(feature) {
+    super(
+      `${feature} is only available in a server environment (Node.js). It cannot run in the browser. Call it from your backend instead.`
+    );
+    this.name = "BrowserEnvironmentError";
+    this.feature = feature;
+  }
+};
+
+// src/env/guard.ts
+function isBrowserEnvironment() {
+  return typeof globalThis !== "undefined" && typeof globalThis.window !== "undefined" && typeof globalThis.document !== "undefined";
+}
+function assertServerEnvironment(feature) {
+  if (isBrowserEnvironment()) {
+    throw new BrowserEnvironmentError(feature);
+  }
+}
+
+// src/graphql/mutation.ts
+var ADD_RECORD_MUTATION = `
+  mutation addSeamlessBoardRecord($createRecordViaApiInput: CreateRecordViaApiInput!) {
+    addSeamlessBoardRecord(createRecordViaApiInput: $createRecordViaApiInput) {
+      _id
+      no
+    }
+  }
+`.trim();
+var ADD_RECORD_OPERATION_NAME = "addSeamlessBoardRecord";
+
+// src/attachments/mime.ts
+var MIME_BY_EXT = {
+  // Documents
+  pdf: "application/pdf",
+  doc: "application/msword",
+  docx: "application/vnd.openxmlformats-officedocument.wordprocessingml.document",
+  xls: "application/vnd.ms-excel",
+  xlsx: "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet",
+  ppt: "application/vnd.ms-powerpoint",
+  pptx: "application/vnd.openxmlformats-officedocument.presentationml.presentation",
+  txt: "text/plain",
+  csv: "text/csv",
+  json: "application/json",
+  xml: "application/xml",
+  // Images
+  png: "image/png",
+  jpg: "image/jpeg",
+  jpeg: "image/jpeg",
+  gif: "image/gif",
+  webp: "image/webp",
+  svg: "image/svg+xml",
+  ico: "image/x-icon",
+  bmp: "image/bmp",
+  // Audio / video
+  mp3: "audio/mpeg",
+  wav: "audio/wav",
+  ogg: "audio/ogg",
+  mp4: "video/mp4",
+  webm: "video/webm",
+  // Archives
+  zip: "application/zip",
+  rar: "application/vnd.rar",
+  "7z": "application/x-7z-compressed",
+  gz: "application/gzip",
+  tar: "application/x-tar"
+};
+function resolveMime(filename, contentType) {
+  if (contentType && contentType.trim()) {
+    return contentType.trim();
+  }
+  const ext = filename.split(".").pop()?.toLowerCase() ?? "";
+  return MIME_BY_EXT[ext] ?? "application/octet-stream";
+}
+
+// src/attachments/file.ts
+var FileUpload = class {
+  content;
+  filename;
+  contentType;
+  /** @internal */
+  constructor(content, filename, contentType) {
+    this.content = content;
+    this.filename = filename;
+    this.contentType = contentType;
+  }
+};
+function file(content, filename, contentType) {
+  return new FileUpload(content, filename, resolveMime(filename, contentType));
+}
+function isFileUpload(value) {
+  return value instanceof FileUpload;
+}
+
+// src/graphql/multipart.ts
+function dummyKey() {
+  return `dummy-${Math.random().toString(36).substring(2, 10)}`;
+}
+function toBlob(upload) {
+  if (upload.content instanceof Blob) {
+    return upload.content.type ? upload.content : new Blob([upload.content], { type: upload.contentType });
+  }
+  return new Blob([upload.content], {
+    type: upload.contentType
+  });
+}
+function transformField(value, fieldId, parts) {
+  if (isFileUpload(value)) {
+    const key = dummyKey();
+    parts.push({
+      key: String(parts.length + 1),
+      path: `variables.createRecordViaApiInput.data.${fieldId}.${key}`,
+      upload: value
+    });
+    return { [key]: null };
+  }
+  if (Array.isArray(value) && value.some(isFileUpload)) {
+    const obj = {};
+    for (const item of value) {
+      if (!isFileUpload(item)) continue;
+      const key = dummyKey();
+      parts.push({
+        key: String(parts.length + 1),
+        path: `variables.createRecordViaApiInput.data.${fieldId}.${key}`,
+        upload: item
+      });
+      obj[key] = null;
+    }
+    return obj;
+  }
+  return value;
+}
+function hasFileUploads(data) {
+  for (const value of Object.values(data)) {
+    if (isFileUpload(value)) return true;
+    if (Array.isArray(value) && value.some(isFileUpload)) return true;
+  }
+  return false;
+}
+function buildMultipartFormData(section, data) {
+  const parts = [];
+  const transformed = {};
+  for (const [fieldId, value] of Object.entries(data)) {
+    transformed[fieldId] = transformField(value, fieldId, parts);
+  }
+  const operations = {
+    query: ADD_RECORD_MUTATION,
+    variables: {
+      createRecordViaApiInput: {
+        section,
+        data: transformed
+      }
+    }
+  };
+  const map = {};
+  for (const part of parts) {
+    map[part.key] = [part.path];
+  }
+  const formData = new FormData();
+  formData.append("operations", JSON.stringify(operations));
+  formData.append("map", JSON.stringify(map));
+  for (const part of parts) {
+    formData.append(part.key, toBlob(part.upload), part.upload.filename);
+  }
+  return { formData, hasAttachments: parts.length > 0 };
+}
+
+// src/http/request.ts
+async function graphqlRequest(options) {
+  const headers = {
+    Authorization: `Bearer ${options.apiKey}`,
+    "x-apollo-operation-name": options.operationName,
+    ...options.headers
+  };
+  if (typeof options.body === "string") {
+    headers["Content-Type"] = "application/json";
+  }
+  const response = await fetch(options.url, {
+    method: "POST",
+    headers,
+    body: options.body
+  });
+  let payload;
+  const text = await response.text();
+  try {
+    payload = text ? JSON.parse(text) : void 0;
+  } catch {
+    throw new ApiError(
+      `Invalid JSON response from GraphQL endpoint (HTTP ${response.status}).`,
+      { status: response.status }
+    );
+  }
+  if (!response.ok) {
+    const message = payload?.errors?.map((e) => e.message).filter(Boolean).join("; ") || `GraphQL request failed with HTTP ${response.status}.`;
+    throw new ApiError(message, {
+      status: response.status,
+      errors: payload?.errors
+    });
+  }
+  if (payload?.errors?.length) {
+    const message = payload.errors.map((e) => e.message).filter(Boolean).join("; ") || "GraphQL request returned errors.";
+    throw new ApiError(message, {
+      status: response.status,
+      errors: payload.errors
+    });
+  }
+  if (!payload?.data) {
+    throw new ApiError("GraphQL response contained no data.", {
+      status: response.status
+    });
+  }
+  return payload.data;
+}
+
+// src/client/SeamlessBoardApi.ts
+var SeamlessBoardApi = class {
+  url;
+  apiKey;
+  /**
+   * @param config - GraphQL endpoint URL and access token.
+   */
+  constructor(config) {
+    if (!config?.url) {
+      throw new Error("SeamlessBoardApi: `url` is required.");
+    }
+    if (!config?.apiKey) {
+      throw new Error("SeamlessBoardApi: `apiKey` is required.");
+    }
+    this.url = config.url;
+    this.apiKey = config.apiKey;
+  }
+  /**
+   * Create a record for the given section.
+   *
+   * - Plain JSON fields → JSON POST.
+   * - Attachment fields (via {@link file}) → GraphQL multipart FormData POST.
+   *
+   * **Server-only:** throws {@link BrowserEnvironmentError} in the browser.
+   *
+   * @param input - Section ID and field data matching the board schema.
+   * @returns The created record `{ _id, no }`.
+   */
+  async addRecord(input) {
+    assertServerEnvironment("SeamlessBoardApi.addRecord");
+    if (!input?.section) {
+      throw new Error("addRecord: `section` is required.");
+    }
+    if (!input?.data || typeof input.data !== "object") {
+      throw new Error("addRecord: `data` is required.");
+    }
+    if (hasFileUploads(input.data)) {
+      return this.addRecordWithAttachments(input);
+    }
+    return this.addRecordJson(input);
+  }
+  /** JSON POST path (no attachments). */
+  async addRecordJson(input) {
+    const data = await graphqlRequest({
+      url: this.url,
+      apiKey: this.apiKey,
+      operationName: ADD_RECORD_OPERATION_NAME,
+      body: JSON.stringify({
+        query: ADD_RECORD_MUTATION,
+        variables: {
+          createRecordViaApiInput: {
+            section: input.section,
+            data: input.data
+          }
+        }
+      })
+    });
+    return data.addSeamlessBoardRecord;
+  }
+  /** Multipart POST path (one or more attachment fields). */
+  async addRecordWithAttachments(input) {
+    const { formData } = buildMultipartFormData(input.section, input.data);
+    const data = await graphqlRequest({
+      url: this.url,
+      apiKey: this.apiKey,
+      operationName: ADD_RECORD_OPERATION_NAME,
+      body: formData
+    });
+    return data.addSeamlessBoardRecord;
+  }
+};
+export {
+  ApiError,
+  AutosocializerError,
+  BrowserEnvironmentError,
+  FileUpload,
+  SeamlessBoardApi,
+  file
+};

package/package.json

@@ -0,0 +1,54 @@
+{
+  "name": "@xtellig/autosocializer",
+  "version": "1.0.0",
+  "description": "The official Node.js SDK for streaming backend server data directly to Autosocializer boards, triggering automated workflows with zero manual intervention",
+  "type": "module",
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "require": "./dist/index.cjs"
+    }
+  },
+  "files": [
+    "dist",
+    "LICENSE",
+    "README.md"
+  ],
+  "scripts": {
+    "build": "tsup",
+    "prepublishOnly": "npm run build"
+  },
+  "keywords": [
+    "xtellig",
+    "autosocializer",
+    "seamless-board",
+    "graphql",
+    "sdk",
+    "api-client"
+  ],
+  "author": "Xtellig",
+  "license": "MIT",
+  "engines": {
+    "node": ">=18"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/xtellig/autosocializer.git"
+  },
+  "homepage": "https://www.xtellig.com",
+  "bugs": {
+    "url": "https://github.com/xtellig/autosocializer/issues"
+  },
+  "devDependencies": {
+    "@types/node": "^22.13.10",
+    "tsup": "^8.4.0",
+    "typescript": "^5.8.2"
+  }
+}