@headroom-cms/api 0.1.4 → 0.1.6

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) {
@@ -105,6 +176,57 @@ var HeadroomClient = class {
     }
     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();
+  }
   // --- Content ---
   async listContent(collection, opts) {
     const params = new URLSearchParams({ collection });
@@ -163,6 +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,
+        ...options.relationships && { relationships: options.relationships }
+      })
+    });
+    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

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) {
@@ -132,6 +204,57 @@ var HeadroomClient = class {
     }
     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();
+  }
   // --- Content ---
   async listContent(collection, opts) {
     const params = new URLSearchParams({ collection });
@@ -190,9 +313,47 @@ 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,
+        ...options.relationships && { relationships: options.relationships }
+      })
+    });
+    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

@@ -61,6 +61,12 @@ interface ContentMetadata {
     coverUrl?: string;
     coverMediaId?: string;
     lastPublishedAt?: number;
+    /** Set to "submission" for submission content, omitted for regular content */
+    mode?: string;
+    /** Site user ID of the submitter (submissions only) */
+    siteUserId?: string;
+    /** Submission field values (submissions only) */
+    fields?: Record<string, unknown>;
 }
 interface ContentItem extends ContentMetadata {
     body?: {
@@ -151,11 +157,73 @@ 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;
+    /** Optional relationships to associate with the submission */
+    relationships?: Record<string, {
+        contentId: 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 +231,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,13 +259,19 @@ 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;
         before?: number;
         after?: number;
-        /** Sort order: "published_desc" (default), "published_asc", "title_asc", "title_desc" */
-        sort?: "published_desc" | "published_asc" | "title_asc" | "title_desc";
+        /** Sort order. For regular queries: "published_desc" (default), "published_asc", "title_asc", "title_desc". For relatedTo queries: "created_desc" (default), "created_asc". */
+        sort?: "published_desc" | "published_asc" | "title_asc" | "title_desc" | "created_desc" | "created_asc";
         /** Find content that has a relationship pointing to this content ID (reverse query) */
         relatedTo?: string;
         /** Filter reverse query to a specific relationship field name */
@@ -218,6 +294,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

@@ -61,6 +61,12 @@ interface ContentMetadata {
     coverUrl?: string;
     coverMediaId?: string;
     lastPublishedAt?: number;
+    /** Set to "submission" for submission content, omitted for regular content */
+    mode?: string;
+    /** Site user ID of the submitter (submissions only) */
+    siteUserId?: string;
+    /** Submission field values (submissions only) */
+    fields?: Record<string, unknown>;
 }
 interface ContentItem extends ContentMetadata {
     body?: {
@@ -151,11 +157,73 @@ 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;
+    /** Optional relationships to associate with the submission */
+    relationships?: Record<string, {
+        contentId: 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 +231,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,13 +259,19 @@ 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;
         before?: number;
         after?: number;
-        /** Sort order: "published_desc" (default), "published_asc", "title_asc", "title_desc" */
-        sort?: "published_desc" | "published_asc" | "title_asc" | "title_desc";
+        /** Sort order. For regular queries: "published_desc" (default), "published_asc", "title_asc", "title_desc". For relatedTo queries: "created_desc" (default), "created_asc". */
+        sort?: "published_desc" | "published_asc" | "title_asc" | "title_desc" | "created_desc" | "created_asc";
         /** Find content that has a relationship pointing to this content ID (reverse query) */
         relatedTo?: string;
         /** Filter reverse query to a specific relationship field name */
@@ -218,6 +294,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) {
@@ -105,6 +176,57 @@ var HeadroomClient = class {
     }
     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();
+  }
   // --- Content ---
   async listContent(collection, opts) {
     const params = new URLSearchParams({ collection });
@@ -163,8 +285,46 @@ 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,
+        ...options.relationships && { relationships: options.relationships }
+      })
+    });
+    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.4",
+  "version": "0.1.6",
   "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"
   }
 }