init commit for iPAL-kit plugin

src/modules/payload/getGlobal.ts

@@ -0,0 +1,29 @@
+import type { BasePayload } from 'payload'
+
+/** Locale argument accepted by the global helpers. */
+export type GlobalQueryOptions = {
+  /** Relationship population depth. Defaults to Payload's config default. */
+  depth?: number
+  /** Locale to fetch, or 'all' for every locale's values. Defaults to Payload's default. */
+  locale?: string
+}
+
+/**
+ * Thin wrapper over payload.findGlobal that keeps locale/depth handling in one
+ * place. The plugin never calls getPayload itself — the caller passes the
+ * instance (from getPayload in their app, or req.payload in a hook), matching
+ * the plugin's data-access rule: logic here, instance from outside.
+ */
+export async function getGlobal<T = Record<string, unknown>>(
+  payload: BasePayload,
+  slug: string,
+  options: GlobalQueryOptions = {},
+): Promise<T> {
+  const result = await payload.findGlobal({
+    slug,
+    ...(options.locale ? { locale: options.locale as never } : {}),
+    ...(typeof options.depth === 'number' ? { depth: options.depth } : {}),
+  })
+
+  return result as T
+}

src/modules/payload/getSiteIntegrations.ts

@@ -0,0 +1,31 @@
+import type { BasePayload } from 'payload'
+
+import type { GlobalQueryOptions } from './getGlobal.js'
+
+import { getGlobal } from './getGlobal.js'
+
+/** Slug of the SiteIntegrations global defined by the plugin. */
+export const SITE_INTEGRATIONS_SLUG = 'site-integrations'
+
+/**
+ * Fetches the SiteIntegrations global.
+ *
+ * This global is admin-only through access control, but the Local API bypasses
+ * access control by default (overrideAccess: true), so server-side callers get
+ * the secrets they need (SMTP password, Turnstile secret, R2 keys). Never
+ * expose the raw result to the client — read the specific values you need
+ * server-side and pass only what's safe to the browser.
+ *
+ * Generic over the return type so the client can pass their generated
+ * `SiteIntegration` type.
+ *
+ * @example
+ * import type { SiteIntegration } from '@/payload-types'
+ * const integrations = await getSiteIntegrations<SiteIntegration>(payload)
+ */
+export function getSiteIntegrations<T = Record<string, unknown>>(
+  payload: BasePayload,
+  options?: GlobalQueryOptions,
+): Promise<T> {
+  return getGlobal<T>(payload, SITE_INTEGRATIONS_SLUG, options)
+}

src/modules/payload/getSiteSettings.ts

@@ -0,0 +1,25 @@
+import type { BasePayload } from 'payload'
+
+import type { GlobalQueryOptions } from './getGlobal.js'
+
+import { getGlobal } from './getGlobal.js'
+
+/** Slug of the SiteSettings global defined by the plugin. */
+export const SITE_SETTINGS_SLUG = 'site-settings'
+
+/**
+ * Fetches the SiteSettings global.
+ *
+ * Generic over the return type so the client can pass their generated
+ * `SiteSetting` type for full type safety, while still working without it.
+ *
+ * @example
+ * import type { SiteSetting } from '@/payload-types'
+ * const settings = await getSiteSettings<SiteSetting>(payload, { locale: 'pl' })
+ */
+export function getSiteSettings<T = Record<string, unknown>>(
+  payload: BasePayload,
+  options?: GlobalQueryOptions,
+): Promise<T> {
+  return getGlobal<T>(payload, SITE_SETTINGS_SLUG, options)
+}

src/modules/payload/index.ts

@@ -0,0 +1,4 @@
+export type { GlobalQueryOptions } from './getGlobal.js'
+export { getGlobal } from './getGlobal.js'
+export { getSiteIntegrations, SITE_INTEGRATIONS_SLUG } from './getSiteIntegrations.js'
+export { getSiteSettings, SITE_SETTINGS_SLUG } from './getSiteSettings.js'