@headroom-cms/api 0.1.3 → 0.1.5

package/dist/astro.js

@@ -1,5 +1,73 @@
 // src/client.ts
 import { createHmac } from "crypto";
+
+// src/auth.ts
+var HeadroomAuth = class {
+  /** @internal */
+  constructor(client) {
+    this.client = client;
+  }
+  /** Request an OTP code be sent to the email address */
+  async requestOTP(email) {
+    await this.client._fetchPost("/auth/otp/request", { email });
+  }
+  /** Verify OTP code and receive a long-lived session token */
+  async verifyOTP(email, code) {
+    return this.client._fetchPost("/auth/otp/verify", {
+      email,
+      code
+    });
+  }
+  /**
+   * Validate a session token and return the user.
+   * Automatically refreshes the token if it's past 75% of its lifetime,
+   * so callers can update their cookie with the new token if wasRefreshed is true.
+   */
+  async getSession(token) {
+    const res = await this.client._fetchWithAuth(
+      "/auth/session",
+      token
+    );
+    const now = Math.floor(Date.now() / 1e3);
+    const remaining = res.expiresAt - now;
+    const lifetime = res.expiresAt - res.issuedAt;
+    if (remaining < lifetime * 0.25) {
+      try {
+        const refreshed = await this.refreshSession(token);
+        return { ...refreshed, wasRefreshed: true };
+      } catch {
+        return {
+          user: res.user,
+          expiresAt: res.expiresAt,
+          token,
+          wasRefreshed: false
+        };
+      }
+    }
+    return {
+      user: res.user,
+      expiresAt: res.expiresAt,
+      token,
+      wasRefreshed: false
+    };
+  }
+  /** Refresh a session token for a new expiry period */
+  async refreshSession(token) {
+    const res = await this.client._fetchPostWithAuth(
+      "/auth/session/refresh",
+      token,
+      {}
+    );
+    return {
+      user: res.user,
+      expiresAt: res.expiresAt,
+      token: res.token,
+      wasRefreshed: true
+    };
+  }
+};
+
+// src/client.ts
 var HeadroomError = class extends Error {
   status;
   code;
@@ -12,11 +80,14 @@ var HeadroomError = class extends Error {
 };
 var HeadroomClient = class {
   config;
+  /** Site user authentication methods */
+  auth;
   constructor(config) {
     this.config = {
       ...config,
       url: config.url.replace(/\/+$/, "")
     };
+    this.auth = new HeadroomAuth(this);
   }
   /** Build the full URL for a public API path */
   apiUrl(path) {
@@ -79,7 +150,7 @@ var HeadroomClient = class {
         message = body.error || message;
       } catch {
       }
-      throw new HeadroomError(res.status, code, message);
+      throw new HeadroomError(res.status, code, `${message} (GET ${url})`);
     }
     return res.json();
   }
@@ -101,7 +172,58 @@ var HeadroomClient = class {
         message = errBody.error || message;
       } catch {
       }
-      throw new HeadroomError(res.status, code, message);
+      throw new HeadroomError(res.status, code, `${message} (POST ${this.apiUrl(path)})`);
+    }
+    return res.json();
+  }
+  /** @internal Used by HeadroomAuth */
+  async _fetchPost(path, body) {
+    return this.fetchPost(path, body);
+  }
+  /** @internal Used by HeadroomAuth — GET with Bearer token */
+  async _fetchWithAuth(path, token) {
+    const url = this.apiUrl(path);
+    const res = await fetch(url, {
+      headers: {
+        "X-Headroom-Key": this.config.apiKey,
+        Authorization: `Bearer ${token}`
+      }
+    });
+    if (!res.ok) {
+      let code = "UNKNOWN";
+      let message = `HTTP ${res.status}`;
+      try {
+        const body = await res.json();
+        code = body.code || code;
+        message = body.error || message;
+      } catch {
+      }
+      throw new HeadroomError(res.status, code, `${message} (GET ${url})`);
+    }
+    return res.json();
+  }
+  /** @internal Used by HeadroomAuth — POST with Bearer token */
+  async _fetchPostWithAuth(path, token, body) {
+    const url = this.apiUrl(path);
+    const res = await fetch(url, {
+      method: "POST",
+      headers: {
+        "X-Headroom-Key": this.config.apiKey,
+        Authorization: `Bearer ${token}`,
+        "Content-Type": "application/json"
+      },
+      body: JSON.stringify(body)
+    });
+    if (!res.ok) {
+      let code = "UNKNOWN";
+      let message = `HTTP ${res.status}`;
+      try {
+        const errBody = await res.json();
+        code = errBody.code || code;
+        message = errBody.error || message;
+      } catch {
+      }
+      throw new HeadroomError(res.status, code, `${message} (POST ${url})`);
     }
     return res.json();
   }
@@ -163,6 +285,40 @@ var HeadroomClient = class {
     const result = await this.fetch("/version");
     return result.contentVersion;
   }
+  // --- Submissions ---
+  /**
+   * Submit content to a submission collection.
+   * Sends a POST to `/v1/{site}/submit/{collection}`.
+   * If a sessionToken is provided, it is sent as the `X-Headroom-Session` header
+   * to associate the submission with an authenticated site user.
+   */
+  async submit(options) {
+    const url = this.apiUrl(`/submit/${encodeURIComponent(options.collection)}`);
+    const headers = {
+      "X-Headroom-Key": this.config.apiKey,
+      "Content-Type": "application/json"
+    };
+    if (options.sessionToken) {
+      headers["X-Headroom-Session"] = options.sessionToken;
+    }
+    const res = await fetch(url, {
+      method: "POST",
+      headers,
+      body: JSON.stringify({ fields: options.fields })
+    });
+    if (!res.ok) {
+      let code = "UNKNOWN";
+      let message = `HTTP ${res.status}`;
+      try {
+        const errBody = await res.json();
+        code = errBody.code || code;
+        message = errBody.error || message;
+      } catch {
+      }
+      throw new HeadroomError(res.status, code, `${message} (POST ${url})`);
+    }
+    return res.json();
+  }
 };
 
 // src/astro/env.ts
@@ -216,7 +372,7 @@ function headroomLoader(opts) {
   return {
     name: "headroom",
     schema: opts.schema,
-    load: async ({ store, meta, generateDigest, parseData }) => {
+    load: async ({ store, meta, generateDigest, parseData, logger }) => {
       const config = opts.config || configFromEnv();
       const client = new HeadroomClient(config);
       try {
@@ -230,14 +386,20 @@ function headroomLoader(opts) {
       }
       const allMetadata = [];
       let cursor;
-      do {
-        const result = await client.listContent(opts.collection, {
-          limit: 1e3,
-          cursor
-        });
-        allMetadata.push(...result.items);
-        cursor = result.hasMore ? result.cursor : void 0;
-      } while (cursor);
+      try {
+        do {
+          const result = await client.listContent(opts.collection, {
+            limit: 1e3,
+            cursor
+          });
+          allMetadata.push(...result.items);
+          cursor = result.hasMore ? result.cursor : void 0;
+        } while (cursor);
+      } catch (e) {
+        const msg = `Failed to load Headroom collection "${opts.collection}" from ${config.url}: ${e instanceof Error ? e.message : e}`;
+        logger.error(msg);
+        throw new Error(msg, { cause: e });
+      }
       const seen = /* @__PURE__ */ new Set();
       const storeId = (item) => item.slug || opts.collection;
       if (opts.bodies) {

package/dist/index.cjs

@@ -20,6 +20,7 @@ var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: tru
 // src/index.ts
 var src_exports = {};
 __export(src_exports, {
+  HeadroomAuth: () => HeadroomAuth,
   HeadroomClient: () => HeadroomClient,
   HeadroomError: () => HeadroomError
 });
@@ -27,6 +28,74 @@ module.exports = __toCommonJS(src_exports);
 
 // src/client.ts
 var import_node_crypto = require("crypto");
+
+// src/auth.ts
+var HeadroomAuth = class {
+  /** @internal */
+  constructor(client) {
+    this.client = client;
+  }
+  /** Request an OTP code be sent to the email address */
+  async requestOTP(email) {
+    await this.client._fetchPost("/auth/otp/request", { email });
+  }
+  /** Verify OTP code and receive a long-lived session token */
+  async verifyOTP(email, code) {
+    return this.client._fetchPost("/auth/otp/verify", {
+      email,
+      code
+    });
+  }
+  /**
+   * Validate a session token and return the user.
+   * Automatically refreshes the token if it's past 75% of its lifetime,
+   * so callers can update their cookie with the new token if wasRefreshed is true.
+   */
+  async getSession(token) {
+    const res = await this.client._fetchWithAuth(
+      "/auth/session",
+      token
+    );
+    const now = Math.floor(Date.now() / 1e3);
+    const remaining = res.expiresAt - now;
+    const lifetime = res.expiresAt - res.issuedAt;
+    if (remaining < lifetime * 0.25) {
+      try {
+        const refreshed = await this.refreshSession(token);
+        return { ...refreshed, wasRefreshed: true };
+      } catch {
+        return {
+          user: res.user,
+          expiresAt: res.expiresAt,
+          token,
+          wasRefreshed: false
+        };
+      }
+    }
+    return {
+      user: res.user,
+      expiresAt: res.expiresAt,
+      token,
+      wasRefreshed: false
+    };
+  }
+  /** Refresh a session token for a new expiry period */
+  async refreshSession(token) {
+    const res = await this.client._fetchPostWithAuth(
+      "/auth/session/refresh",
+      token,
+      {}
+    );
+    return {
+      user: res.user,
+      expiresAt: res.expiresAt,
+      token: res.token,
+      wasRefreshed: true
+    };
+  }
+};
+
+// src/client.ts
 var HeadroomError = class extends Error {
   status;
   code;
@@ -39,11 +108,14 @@ var HeadroomError = class extends Error {
 };
 var HeadroomClient = class {
   config;
+  /** Site user authentication methods */
+  auth;
   constructor(config) {
     this.config = {
       ...config,
       url: config.url.replace(/\/+$/, "")
     };
+    this.auth = new HeadroomAuth(this);
   }
   /** Build the full URL for a public API path */
   apiUrl(path) {
@@ -106,7 +178,7 @@ var HeadroomClient = class {
         message = body.error || message;
       } catch {
       }
-      throw new HeadroomError(res.status, code, message);
+      throw new HeadroomError(res.status, code, `${message} (GET ${url})`);
     }
     return res.json();
   }
@@ -128,7 +200,58 @@ var HeadroomClient = class {
         message = errBody.error || message;
       } catch {
       }
-      throw new HeadroomError(res.status, code, message);
+      throw new HeadroomError(res.status, code, `${message} (POST ${this.apiUrl(path)})`);
+    }
+    return res.json();
+  }
+  /** @internal Used by HeadroomAuth */
+  async _fetchPost(path, body) {
+    return this.fetchPost(path, body);
+  }
+  /** @internal Used by HeadroomAuth — GET with Bearer token */
+  async _fetchWithAuth(path, token) {
+    const url = this.apiUrl(path);
+    const res = await fetch(url, {
+      headers: {
+        "X-Headroom-Key": this.config.apiKey,
+        Authorization: `Bearer ${token}`
+      }
+    });
+    if (!res.ok) {
+      let code = "UNKNOWN";
+      let message = `HTTP ${res.status}`;
+      try {
+        const body = await res.json();
+        code = body.code || code;
+        message = body.error || message;
+      } catch {
+      }
+      throw new HeadroomError(res.status, code, `${message} (GET ${url})`);
+    }
+    return res.json();
+  }
+  /** @internal Used by HeadroomAuth — POST with Bearer token */
+  async _fetchPostWithAuth(path, token, body) {
+    const url = this.apiUrl(path);
+    const res = await fetch(url, {
+      method: "POST",
+      headers: {
+        "X-Headroom-Key": this.config.apiKey,
+        Authorization: `Bearer ${token}`,
+        "Content-Type": "application/json"
+      },
+      body: JSON.stringify(body)
+    });
+    if (!res.ok) {
+      let code = "UNKNOWN";
+      let message = `HTTP ${res.status}`;
+      try {
+        const errBody = await res.json();
+        code = errBody.code || code;
+        message = errBody.error || message;
+      } catch {
+      }
+      throw new HeadroomError(res.status, code, `${message} (POST ${url})`);
     }
     return res.json();
   }
@@ -190,9 +313,44 @@ var HeadroomClient = class {
     const result = await this.fetch("/version");
     return result.contentVersion;
   }
+  // --- Submissions ---
+  /**
+   * Submit content to a submission collection.
+   * Sends a POST to `/v1/{site}/submit/{collection}`.
+   * If a sessionToken is provided, it is sent as the `X-Headroom-Session` header
+   * to associate the submission with an authenticated site user.
+   */
+  async submit(options) {
+    const url = this.apiUrl(`/submit/${encodeURIComponent(options.collection)}`);
+    const headers = {
+      "X-Headroom-Key": this.config.apiKey,
+      "Content-Type": "application/json"
+    };
+    if (options.sessionToken) {
+      headers["X-Headroom-Session"] = options.sessionToken;
+    }
+    const res = await fetch(url, {
+      method: "POST",
+      headers,
+      body: JSON.stringify({ fields: options.fields })
+    });
+    if (!res.ok) {
+      let code = "UNKNOWN";
+      let message = `HTTP ${res.status}`;
+      try {
+        const errBody = await res.json();
+        code = errBody.code || code;
+        message = errBody.error || message;
+      } catch {
+      }
+      throw new HeadroomError(res.status, code, `${message} (POST ${url})`);
+    }
+    return res.json();
+  }
 };
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
+  HeadroomAuth,
   HeadroomClient,
   HeadroomError
 });

package/dist/index.d.cts

@@ -151,11 +151,69 @@ interface TransformOptions {
     /** Quality (1-100) */
     quality?: number;
 }
+/** Options for submitting content to a submission collection. */
+interface SubmitOptions {
+    /** The submission collection name */
+    collection: string;
+    /** Field values for the submission */
+    fields: Record<string, unknown>;
+    /** Optional site user session token (adds X-Headroom-Session header) */
+    sessionToken?: string;
+}
+/** Result returned from a successful submission. */
+interface SubmitResult {
+    /** The ID of the created content item */
+    contentId: string;
+    /** Unix timestamp of creation */
+    createdAt: number;
+    /** Site user ID if the submission was authenticated */
+    siteUserId?: string;
+}
 interface HeadroomErrorBody {
     error: string;
     code?: string;
 }
 
+interface AuthResult {
+    token: string;
+    expiresAt: number;
+    user: AuthUser;
+}
+interface AuthUser {
+    userId: string;
+    email: string;
+    name?: string;
+    tags?: string[];
+    fields?: Record<string, unknown>;
+}
+interface AuthSession {
+    user: AuthUser;
+    expiresAt: number;
+    token: string;
+    wasRefreshed: boolean;
+}
+/**
+ * HeadroomAuth provides site user authentication methods.
+ * Access via `client.auth`.
+ */
+declare class HeadroomAuth {
+    private client;
+    /** @internal */
+    constructor(client: HeadroomClient);
+    /** Request an OTP code be sent to the email address */
+    requestOTP(email: string): Promise<void>;
+    /** Verify OTP code and receive a long-lived session token */
+    verifyOTP(email: string, code: string): Promise<AuthResult>;
+    /**
+     * Validate a session token and return the user.
+     * Automatically refreshes the token if it's past 75% of its lifetime,
+     * so callers can update their cookie with the new token if wasRefreshed is true.
+     */
+    getSession(token: string): Promise<AuthSession>;
+    /** Refresh a session token for a new expiry period */
+    refreshSession(token: string): Promise<AuthSession>;
+}
+
 declare class HeadroomError extends Error {
     status: number;
     code: string;
@@ -163,6 +221,8 @@ declare class HeadroomError extends Error {
 }
 declare class HeadroomClient {
     private config;
+    /** Site user authentication methods */
+    readonly auth: HeadroomAuth;
     constructor(config: HeadroomConfig);
     /** Build the full URL for a public API path */
     private apiUrl;
@@ -189,6 +249,12 @@ declare class HeadroomClient {
     transformUrl(path: string | undefined, opts?: TransformOptions): string;
     private fetch;
     private fetchPost;
+    /** @internal Used by HeadroomAuth */
+    _fetchPost<T>(path: string, body: unknown): Promise<T>;
+    /** @internal Used by HeadroomAuth — GET with Bearer token */
+    _fetchWithAuth<T>(path: string, token: string): Promise<T>;
+    /** @internal Used by HeadroomAuth — POST with Bearer token */
+    _fetchPostWithAuth<T>(path: string, token: string, body: unknown): Promise<T>;
     listContent(collection: string, opts?: {
         limit?: number;
         cursor?: string;
@@ -218,6 +284,13 @@ declare class HeadroomClient {
     getCollection(name: string): Promise<Collection>;
     listBlockTypes(): Promise<BlockTypeListResult>;
     getVersion(): Promise<number>;
+    /**
+     * Submit content to a submission collection.
+     * Sends a POST to `/v1/{site}/submit/{collection}`.
+     * If a sessionToken is provided, it is sent as the `X-Headroom-Session` header
+     * to associate the submission with an authenticated site user.
+     */
+    submit(options: SubmitOptions): Promise<SubmitResult>;
 }
 
-export { type BatchContentResult, type Block, type BlockTypeDef, type BlockTypeListResult, type Collection, type CollectionListResult, type CollectionSummary, type ContentItem, type ContentListResult, type ContentMetadata, type ContentRef, type FieldDef, HeadroomClient, type HeadroomConfig, HeadroomError, type HeadroomErrorBody, type InlineContent, type LinkContent, type PublicContentRef, type RefsMap, type RelationshipDef, type TableContent, type TableRow, type TextContent, type TextStyles, type TransformOptions };
+export { type AuthResult, type AuthSession, type AuthUser, type BatchContentResult, type Block, type BlockTypeDef, type BlockTypeListResult, type Collection, type CollectionListResult, type CollectionSummary, type ContentItem, type ContentListResult, type ContentMetadata, type ContentRef, type FieldDef, HeadroomAuth, HeadroomClient, type HeadroomConfig, HeadroomError, type HeadroomErrorBody, type InlineContent, type LinkContent, type PublicContentRef, type RefsMap, type RelationshipDef, type SubmitOptions, type SubmitResult, type TableContent, type TableRow, type TextContent, type TextStyles, type TransformOptions };

package/dist/index.d.ts

@@ -151,11 +151,69 @@ interface TransformOptions {
     /** Quality (1-100) */
     quality?: number;
 }
+/** Options for submitting content to a submission collection. */
+interface SubmitOptions {
+    /** The submission collection name */
+    collection: string;
+    /** Field values for the submission */
+    fields: Record<string, unknown>;
+    /** Optional site user session token (adds X-Headroom-Session header) */
+    sessionToken?: string;
+}
+/** Result returned from a successful submission. */
+interface SubmitResult {
+    /** The ID of the created content item */
+    contentId: string;
+    /** Unix timestamp of creation */
+    createdAt: number;
+    /** Site user ID if the submission was authenticated */
+    siteUserId?: string;
+}
 interface HeadroomErrorBody {
     error: string;
     code?: string;
 }
 
+interface AuthResult {
+    token: string;
+    expiresAt: number;
+    user: AuthUser;
+}
+interface AuthUser {
+    userId: string;
+    email: string;
+    name?: string;
+    tags?: string[];
+    fields?: Record<string, unknown>;
+}
+interface AuthSession {
+    user: AuthUser;
+    expiresAt: number;
+    token: string;
+    wasRefreshed: boolean;
+}
+/**
+ * HeadroomAuth provides site user authentication methods.
+ * Access via `client.auth`.
+ */
+declare class HeadroomAuth {
+    private client;
+    /** @internal */
+    constructor(client: HeadroomClient);
+    /** Request an OTP code be sent to the email address */
+    requestOTP(email: string): Promise<void>;
+    /** Verify OTP code and receive a long-lived session token */
+    verifyOTP(email: string, code: string): Promise<AuthResult>;
+    /**
+     * Validate a session token and return the user.
+     * Automatically refreshes the token if it's past 75% of its lifetime,
+     * so callers can update their cookie with the new token if wasRefreshed is true.
+     */
+    getSession(token: string): Promise<AuthSession>;
+    /** Refresh a session token for a new expiry period */
+    refreshSession(token: string): Promise<AuthSession>;
+}
+
 declare class HeadroomError extends Error {
     status: number;
     code: string;
@@ -163,6 +221,8 @@ declare class HeadroomError extends Error {
 }
 declare class HeadroomClient {
     private config;
+    /** Site user authentication methods */
+    readonly auth: HeadroomAuth;
     constructor(config: HeadroomConfig);
     /** Build the full URL for a public API path */
     private apiUrl;
@@ -189,6 +249,12 @@ declare class HeadroomClient {
     transformUrl(path: string | undefined, opts?: TransformOptions): string;
     private fetch;
     private fetchPost;
+    /** @internal Used by HeadroomAuth */
+    _fetchPost<T>(path: string, body: unknown): Promise<T>;
+    /** @internal Used by HeadroomAuth — GET with Bearer token */
+    _fetchWithAuth<T>(path: string, token: string): Promise<T>;
+    /** @internal Used by HeadroomAuth — POST with Bearer token */
+    _fetchPostWithAuth<T>(path: string, token: string, body: unknown): Promise<T>;
     listContent(collection: string, opts?: {
         limit?: number;
         cursor?: string;
@@ -218,6 +284,13 @@ declare class HeadroomClient {
     getCollection(name: string): Promise<Collection>;
     listBlockTypes(): Promise<BlockTypeListResult>;
     getVersion(): Promise<number>;
+    /**
+     * Submit content to a submission collection.
+     * Sends a POST to `/v1/{site}/submit/{collection}`.
+     * If a sessionToken is provided, it is sent as the `X-Headroom-Session` header
+     * to associate the submission with an authenticated site user.
+     */
+    submit(options: SubmitOptions): Promise<SubmitResult>;
 }
 
-export { type BatchContentResult, type Block, type BlockTypeDef, type BlockTypeListResult, type Collection, type CollectionListResult, type CollectionSummary, type ContentItem, type ContentListResult, type ContentMetadata, type ContentRef, type FieldDef, HeadroomClient, type HeadroomConfig, HeadroomError, type HeadroomErrorBody, type InlineContent, type LinkContent, type PublicContentRef, type RefsMap, type RelationshipDef, type TableContent, type TableRow, type TextContent, type TextStyles, type TransformOptions };
+export { type AuthResult, type AuthSession, type AuthUser, type BatchContentResult, type Block, type BlockTypeDef, type BlockTypeListResult, type Collection, type CollectionListResult, type CollectionSummary, type ContentItem, type ContentListResult, type ContentMetadata, type ContentRef, type FieldDef, HeadroomAuth, HeadroomClient, type HeadroomConfig, HeadroomError, type HeadroomErrorBody, type InlineContent, type LinkContent, type PublicContentRef, type RefsMap, type RelationshipDef, type SubmitOptions, type SubmitResult, type TableContent, type TableRow, type TextContent, type TextStyles, type TransformOptions };

package/dist/index.js

@@ -1,5 +1,73 @@
 // src/client.ts
 import { createHmac } from "crypto";
+
+// src/auth.ts
+var HeadroomAuth = class {
+  /** @internal */
+  constructor(client) {
+    this.client = client;
+  }
+  /** Request an OTP code be sent to the email address */
+  async requestOTP(email) {
+    await this.client._fetchPost("/auth/otp/request", { email });
+  }
+  /** Verify OTP code and receive a long-lived session token */
+  async verifyOTP(email, code) {
+    return this.client._fetchPost("/auth/otp/verify", {
+      email,
+      code
+    });
+  }
+  /**
+   * Validate a session token and return the user.
+   * Automatically refreshes the token if it's past 75% of its lifetime,
+   * so callers can update their cookie with the new token if wasRefreshed is true.
+   */
+  async getSession(token) {
+    const res = await this.client._fetchWithAuth(
+      "/auth/session",
+      token
+    );
+    const now = Math.floor(Date.now() / 1e3);
+    const remaining = res.expiresAt - now;
+    const lifetime = res.expiresAt - res.issuedAt;
+    if (remaining < lifetime * 0.25) {
+      try {
+        const refreshed = await this.refreshSession(token);
+        return { ...refreshed, wasRefreshed: true };
+      } catch {
+        return {
+          user: res.user,
+          expiresAt: res.expiresAt,
+          token,
+          wasRefreshed: false
+        };
+      }
+    }
+    return {
+      user: res.user,
+      expiresAt: res.expiresAt,
+      token,
+      wasRefreshed: false
+    };
+  }
+  /** Refresh a session token for a new expiry period */
+  async refreshSession(token) {
+    const res = await this.client._fetchPostWithAuth(
+      "/auth/session/refresh",
+      token,
+      {}
+    );
+    return {
+      user: res.user,
+      expiresAt: res.expiresAt,
+      token: res.token,
+      wasRefreshed: true
+    };
+  }
+};
+
+// src/client.ts
 var HeadroomError = class extends Error {
   status;
   code;
@@ -12,11 +80,14 @@ var HeadroomError = class extends Error {
 };
 var HeadroomClient = class {
   config;
+  /** Site user authentication methods */
+  auth;
   constructor(config) {
     this.config = {
       ...config,
       url: config.url.replace(/\/+$/, "")
     };
+    this.auth = new HeadroomAuth(this);
   }
   /** Build the full URL for a public API path */
   apiUrl(path) {
@@ -79,7 +150,7 @@ var HeadroomClient = class {
         message = body.error || message;
       } catch {
       }
-      throw new HeadroomError(res.status, code, message);
+      throw new HeadroomError(res.status, code, `${message} (GET ${url})`);
     }
     return res.json();
   }
@@ -101,7 +172,58 @@ var HeadroomClient = class {
         message = errBody.error || message;
       } catch {
       }
-      throw new HeadroomError(res.status, code, message);
+      throw new HeadroomError(res.status, code, `${message} (POST ${this.apiUrl(path)})`);
+    }
+    return res.json();
+  }
+  /** @internal Used by HeadroomAuth */
+  async _fetchPost(path, body) {
+    return this.fetchPost(path, body);
+  }
+  /** @internal Used by HeadroomAuth — GET with Bearer token */
+  async _fetchWithAuth(path, token) {
+    const url = this.apiUrl(path);
+    const res = await fetch(url, {
+      headers: {
+        "X-Headroom-Key": this.config.apiKey,
+        Authorization: `Bearer ${token}`
+      }
+    });
+    if (!res.ok) {
+      let code = "UNKNOWN";
+      let message = `HTTP ${res.status}`;
+      try {
+        const body = await res.json();
+        code = body.code || code;
+        message = body.error || message;
+      } catch {
+      }
+      throw new HeadroomError(res.status, code, `${message} (GET ${url})`);
+    }
+    return res.json();
+  }
+  /** @internal Used by HeadroomAuth — POST with Bearer token */
+  async _fetchPostWithAuth(path, token, body) {
+    const url = this.apiUrl(path);
+    const res = await fetch(url, {
+      method: "POST",
+      headers: {
+        "X-Headroom-Key": this.config.apiKey,
+        Authorization: `Bearer ${token}`,
+        "Content-Type": "application/json"
+      },
+      body: JSON.stringify(body)
+    });
+    if (!res.ok) {
+      let code = "UNKNOWN";
+      let message = `HTTP ${res.status}`;
+      try {
+        const errBody = await res.json();
+        code = errBody.code || code;
+        message = errBody.error || message;
+      } catch {
+      }
+      throw new HeadroomError(res.status, code, `${message} (POST ${url})`);
     }
     return res.json();
   }
@@ -163,8 +285,43 @@ var HeadroomClient = class {
     const result = await this.fetch("/version");
     return result.contentVersion;
   }
+  // --- Submissions ---
+  /**
+   * Submit content to a submission collection.
+   * Sends a POST to `/v1/{site}/submit/{collection}`.
+   * If a sessionToken is provided, it is sent as the `X-Headroom-Session` header
+   * to associate the submission with an authenticated site user.
+   */
+  async submit(options) {
+    const url = this.apiUrl(`/submit/${encodeURIComponent(options.collection)}`);
+    const headers = {
+      "X-Headroom-Key": this.config.apiKey,
+      "Content-Type": "application/json"
+    };
+    if (options.sessionToken) {
+      headers["X-Headroom-Session"] = options.sessionToken;
+    }
+    const res = await fetch(url, {
+      method: "POST",
+      headers,
+      body: JSON.stringify({ fields: options.fields })
+    });
+    if (!res.ok) {
+      let code = "UNKNOWN";
+      let message = `HTTP ${res.status}`;
+      try {
+        const errBody = await res.json();
+        code = errBody.code || code;
+        message = errBody.error || message;
+      } catch {
+      }
+      throw new HeadroomError(res.status, code, `${message} (POST ${url})`);
+    }
+    return res.json();
+  }
 };
 export {
+  HeadroomAuth,
   HeadroomClient,
   HeadroomError
 };

package/dist/next.cjs

@@ -0,0 +1,68 @@
+"use client";
+"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/next.ts
+var next_exports = {};
+__export(next_exports, {
+  DevRefresh: () => DevRefresh
+});
+module.exports = __toCommonJS(next_exports);
+
+// src/next/DevRefresh.tsx
+var import_react = require("react");
+var import_navigation = require("next/navigation");
+function DevRefresh({
+  versionUrl,
+  apiKey,
+  interval = 2e3
+}) {
+  const router = (0, import_navigation.useRouter)();
+  const lastVersion = (0, import_react.useRef)(null);
+  (0, import_react.useEffect)(() => {
+    const controller = new AbortController();
+    const poll = async () => {
+      try {
+        const res = await fetch(versionUrl, {
+          headers: { "X-Headroom-Key": apiKey },
+          signal: controller.signal
+        });
+        if (!res.ok) return;
+        const data = await res.json();
+        const version = data.contentVersion;
+        if (lastVersion.current !== null && version !== lastVersion.current) {
+          router.refresh();
+        }
+        lastVersion.current = version;
+      } catch {
+      }
+    };
+    const id = setInterval(poll, interval);
+    poll();
+    return () => {
+      controller.abort();
+      clearInterval(id);
+    };
+  }, [versionUrl, apiKey, interval, router]);
+  return null;
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  DevRefresh
+});

package/dist/next.d.cts

@@ -0,0 +1,11 @@
+interface DevRefreshProps {
+    /** URL to poll for version changes (full URL to /v1/{site}/version) */
+    versionUrl: string;
+    /** API key header value */
+    apiKey: string;
+    /** Poll interval in milliseconds (default: 2000) */
+    interval?: number;
+}
+declare function DevRefresh({ versionUrl, apiKey, interval, }: DevRefreshProps): null;
+
+export { DevRefresh, type DevRefreshProps };

package/dist/next.d.ts

@@ -0,0 +1,11 @@
+interface DevRefreshProps {
+    /** URL to poll for version changes (full URL to /v1/{site}/version) */
+    versionUrl: string;
+    /** API key header value */
+    apiKey: string;
+    /** Poll interval in milliseconds (default: 2000) */
+    interval?: number;
+}
+declare function DevRefresh({ versionUrl, apiKey, interval, }: DevRefreshProps): null;
+
+export { DevRefresh, type DevRefreshProps };

package/dist/next.js

@@ -0,0 +1,42 @@
+"use client";
+
+// src/next/DevRefresh.tsx
+import { useEffect, useRef } from "react";
+import { useRouter } from "next/navigation";
+function DevRefresh({
+  versionUrl,
+  apiKey,
+  interval = 2e3
+}) {
+  const router = useRouter();
+  const lastVersion = useRef(null);
+  useEffect(() => {
+    const controller = new AbortController();
+    const poll = async () => {
+      try {
+        const res = await fetch(versionUrl, {
+          headers: { "X-Headroom-Key": apiKey },
+          signal: controller.signal
+        });
+        if (!res.ok) return;
+        const data = await res.json();
+        const version = data.contentVersion;
+        if (lastVersion.current !== null && version !== lastVersion.current) {
+          router.refresh();
+        }
+        lastVersion.current = version;
+      } catch {
+      }
+    };
+    const id = setInterval(poll, interval);
+    poll();
+    return () => {
+      controller.abort();
+      clearInterval(id);
+    };
+  }, [versionUrl, apiKey, interval, router]);
+  return null;
+}
+export {
+  DevRefresh
+};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@headroom-cms/api",
-  "version": "0.1.3",
+  "version": "0.1.5",
   "type": "module",
   "exports": {
     ".": {
@@ -19,6 +19,11 @@
       "types": "./dist/astro.d.ts",
       "import": "./dist/astro.js"
     },
+    "./next": {
+      "types": "./dist/next.d.ts",
+      "import": "./dist/next.js",
+      "require": "./dist/next.cjs"
+    },
     "./codegen": {
       "types": "./dist/codegen.d.ts",
       "import": "./dist/codegen.js",
@@ -41,9 +46,10 @@
     "typecheck": "tsc --noEmit"
   },
   "peerDependencies": {
+    "astro": ">=5",
+    "next": ">=14",
     "react": ">=18",
-    "react-dom": ">=18",
-    "astro": ">=5"
+    "react-dom": ">=18"
   },
   "peerDependenciesMeta": {
     "react": {
@@ -54,19 +60,23 @@
     },
     "astro": {
       "optional": true
+    },
+    "next": {
+      "optional": true
     }
   },
   "devDependencies": {
     "@testing-library/jest-dom": "~6.6.3",
     "@testing-library/react": "~16.3.0",
+    "@types/node": "~22.0.0",
     "@types/react": "~19.1.0",
+    "astro": "^5.0.0",
     "jsdom": "~26.1.0",
+    "next": "^16.2.1",
     "react": "~19.1.0",
     "react-dom": "~19.1.0",
     "tsup": "~8.5.0",
     "typescript": "~5.9.3",
-    "astro": "^5.0.0",
-    "@types/node": "~22.0.0",
     "vitest": "~4.0.18"
   }
 }