/**
 * DataGuard API client — server-only.
 *
 * This file is the single place to look for "how do I call the Sidian
 * DataGuard org API from a Node/Next.js backend". Copy this file into your
 * own project alongside a `DATAGUARD_API_KEY` env var and you're set.
 *
 * All endpoints are `POST` against `${BASE}/...` with a JSON body.
 * Full reference: https://api.sidian.io/org/<your-org>/ (see Admin Portal).
 */

import "server-only";

/**
 * Set `DATAGUARD_ORG` in your env to your org slug — this is the `<your_org>`
 * path segment in the DataGuard API URL. Example: `DATAGUARD_ORG=acme-corp`.
 */
const ORG = process.env.DATAGUARD_ORG ?? "<your_org>";
const BASE = `https://api.sidian.io/org/${ORG}`;

function getKey(): string {
  const k = process.env.DATAGUARD_API_KEY;
  if (!k) throw new Error("DATAGUARD_API_KEY is not set");
  return k;
}

// ─── Request shapes ──────────────────────────────────────────────────────

/**
 * Content to analyze. `text` and `url` variants also exist; this app uses
 * `content` (inline base64 upload) for small files and `multipart` (upload
 * session handle) for anything larger than a few MiB — see §10 of the
 * DataGuard API docs.
 */
export type Source =
  | {
      type: "content";
      base64Content: string;
      filename: string;
      mimeType: string;
    }
  | {
      type: "multipart";
      uploadId: string;
    };

/** One REDACT/EXCLUDE rule inside `rules.pdf[]` for `/redact`. */
export type PdfRule = {
  action: "REDACT" | "EXCLUDE";
  target: "WORDS" | "PARAGRAPHS" | "PAGES";
  text?: string;
  pages?: number[];
};

// ─── Response shapes ─────────────────────────────────────────────────────

/** One category entry in `/analyze/review`. RETAIN-action entities are omitted by the API. */
export type ReviewItem = {
  category: string;
  action: string;
  reference: string;
  items: string[];
  recommendation?: string;
};

export type ReviewResponse = {
  review: ReviewItem[];
  summary: string;
  stats: Record<string, number>;
};

/** `/scan` returns raw NER — an object keyed by entity type (e.g. "PERSON_NAME", "SSN"). */
export type ScanEntity = {
  action?: string;
  reference?: string;
  items: string[];
};

export type ScanResponse = {
  entities: Record<string, ScanEntity>;
  summary?: string;
  stats: { entitiesFound: number; processingTimeMs: number };
};

/** `/redact` and `/analyze/auto` both return the redacted file as base64 plus stats. */
export type RedactResponse = {
  base64Content: string;
  filename: string;
  mimeType: string;
  entities: Record<string, ScanEntity> | unknown;
  summary: string;
  stats: Record<string, number>;
};

/** `/analyze/auto` response shape matches `/redact`. */
export type AutoResponse = RedactResponse;

// ─── Multipart upload shapes ─────────────────────────────────────────────

/** `POST /uploads` response — opens a session. */
export type UploadInitResponse = {
  uploadId: string;
  partSize: number;
  minPartSize: number;
  maxParts: number;
  expiresAt: string;
};

/** `PUT /uploads/{uploadId}/parts/{partNumber}` response. */
export type UploadPartResponse = {
  partNumber: number;
  etag: string;
  size: number;
};

/** `POST /uploads/{uploadId}/complete` response. Returns a reusable `source`. */
export type UploadCompleteResponse = {
  uploadId: string;
  filename: string;
  size: number;
  mimeType: string;
  source: { type: "multipart"; uploadId: string };
};

// ─── Transport ───────────────────────────────────────────────────────────

async function throwUpstream(res: Response, label: string): Promise<never> {
  const text = await res.text();
  throw Object.assign(new Error(`DataGuard ${label} failed: ${text}`), { status: res.status });
}

async function dataguardPost<T>(path: string, body: unknown, label: string): Promise<T> {
  const res = await fetch(`${BASE}${path}`, {
    method: "POST",
    headers: {
      "Content-Type": "application/json",
      Authorization: `Bearer ${getKey()}`,
    },
    body: JSON.stringify(body),
  });
  if (!res.ok) await throwUpstream(res, label);
  return res.json() as Promise<T>;
}

// ─── Endpoints ───────────────────────────────────────────────────────────

/**
 * `POST /analyze/review` — full analysis returning structured review feedback.
 * Per-entity `action` + policy `reference` + human-readable `recommendation`.
 * Does not mutate the file. Use when you want a human to pick what to redact.
 */
export async function review(source: Source): Promise<ReviewResponse> {
  return dataguardPost<ReviewResponse>("/analyze/review", { source }, "review");
}

/**
 * `POST /redact` — pure rule-based redaction. Applies `rules` to the uploaded
 * file with no NER or policy analysis. Returns the redacted file as base64.
 * Supports PDF/DOCX/PPTX (via `rules.pdf[]`) and XLSX/XLS (via `rules.xlsx[]`).
 */
export async function redact(source: Source, rules: { pdf?: PdfRule[] }): Promise<RedactResponse> {
  return dataguardPost<RedactResponse>("/redact", { source, rules }, "redact");
}

/**
 * `POST /analyze/auto` — full analysis + automatic redaction in one call.
 * Runs NER + policy, auto-generates rules from REDACT-action entities, and
 * returns the redacted file as base64. The one-shot version of `review`→`redact`.
 */
export async function auto(source: Source): Promise<AutoResponse> {
  return dataguardPost<AutoResponse>("/analyze/auto", { source }, "auto");
}

// ─── Multipart upload helpers ────────────────────────────────────────────

/**
 * `POST /uploads` — open a multipart session. Use for files larger than a
 * few MiB. DataGuard returns an `uploadId` plus the `partSize` to chunk
 * against. Pass the `uploadId` back into any content endpoint as
 * `source: { type: "multipart", uploadId }` once `completeUpload` succeeds.
 */
export async function initiateUpload(input: {
  filename: string;
  mimeType?: string;
  size?: number;
  partSize?: number;
}): Promise<UploadInitResponse> {
  const res = await fetch(`${BASE}/uploads`, {
    method: "POST",
    headers: {
      "Content-Type": "application/json",
      Authorization: `Bearer ${getKey()}`,
    },
    body: JSON.stringify(input),
  });
  if (!res.ok) await throwUpstream(res, "initiateUpload");
  return res.json() as Promise<UploadInitResponse>;
}

/**
 * `PUT /uploads/{uploadId}/parts/{partNumber}` — stream a single part.
 * Body is raw binary bytes; `body` may be a `ReadableStream` (streamed
 * straight from the client request) or a `BodyInit` buffer.
 *
 * `contentLength` should be set when `body` is a stream — fetch can't infer
 * the length of a half-duplex stream, and DataGuard rejects parts that
 * don't declare a length.
 */
export async function uploadPart(
  uploadId: string,
  partNumber: number,
  body: BodyInit,
  contentLength?: number,
): Promise<UploadPartResponse> {
  const headers: Record<string, string> = {
    "Content-Type": "application/octet-stream",
    Authorization: `Bearer ${getKey()}`,
  };
  if (contentLength !== undefined) headers["Content-Length"] = String(contentLength);

  const init: RequestInit & { duplex?: "half" } = {
    method: "PUT",
    headers,
    body,
  };
  // Required when streaming a ReadableStream as the request body on Node.
  if (body instanceof ReadableStream) init.duplex = "half";

  const res = await fetch(`${BASE}/uploads/${uploadId}/parts/${partNumber}`, init);
  if (!res.ok) await throwUpstream(res, "uploadPart");
  return res.json() as Promise<UploadPartResponse>;
}

/**
 * `POST /uploads/{uploadId}/complete` — finalize and produce a reusable
 * `source` handle. `parts` must be the full `{ partNumber, etag }` list.
 */
export async function completeUpload(
  uploadId: string,
  parts: { partNumber: number; etag: string }[],
): Promise<UploadCompleteResponse> {
  const res = await fetch(`${BASE}/uploads/${uploadId}/complete`, {
    method: "POST",
    headers: {
      "Content-Type": "application/json",
      Authorization: `Bearer ${getKey()}`,
    },
    body: JSON.stringify({ parts }),
  });
  if (!res.ok) await throwUpstream(res, "completeUpload");
  return res.json() as Promise<UploadCompleteResponse>;
}

/**
 * `DELETE /uploads/{uploadId}` — abort a session and release scratch space.
 * Idempotent if the session isn't currently being consumed.
 */
export async function abortUpload(uploadId: string): Promise<void> {
  const res = await fetch(`${BASE}/uploads/${uploadId}`, {
    method: "DELETE",
    headers: { Authorization: `Bearer ${getKey()}` },
  });
  if (!res.ok && res.status !== 204) await throwUpstream(res, "abortUpload");
}

/**
 * `POST /scan` — raw named-entity recognition. Returns every detected entity
 * keyed by entity type, with no policy evaluation or file mutation. Use when
 * you just want to know what's in the document.
 */
export async function scan(source: Source): Promise<ScanResponse> {
  const raw = await dataguardPost<{
    entities: Record<string, ScanEntity | string[]>;
    summary: string;
    stats: { entitiesFound: number; processingTimeMs: number };
  }>("/scan", { source }, "scan");

  // Tolerate both `{ PERSON_NAME: { items: [...] } }` and `{ PERSON_NAME: [...] }` shapes.
  const entities: Record<string, ScanEntity> = {};
  for (const [type, value] of Object.entries(raw.entities ?? {})) {
    entities[type] = Array.isArray(value) ? { items: value } : value;
  }
  return { ...raw, entities };
}
Entity Scan

Source code for your stack
