@aihu/magna

async function beforeCompile(ctx: MagnaBuildContext): Promise<void>

Run the beforeCompile SDL pipeline.

function createMagnaFetch(options: MagnaPluginOptions): MagnaFetch

Create a typed GraphQL fetch function bound to the given options.

function createMagnaResource<T>( fetch: MagnaFetch, operation: string, variables?: Signal<Readonly<Record<string, unknown>> | null>, options?: ResourceOptions<T>, ): MagnaResource<T>

Create a reactive Magna GraphQL resource.

function useMagnaSubscription<T>(): MagnaSubscriptionHandle<T>

Return a degraded subscription handle.

const MagnaFetchToken

interface MagnaBuildContext extends BuildContext {
  readonly magna: {
    readonly options: MagnaPluginOptions
    readonly untyped: boolean
    readonly outputPath: string
    readonly warnings: ReadonlyArray<string>
  }
}

Extended build context passed to the magna beforeCompile hook.

interface MagnaJwtRelay {
  readonly ssr: {
    readonly source: 'request-context'
    readonly extractor: 'requireAuth(req) → token → wrap in getToken closure'
  }
  readonly client: {
    readonly source: 'cookie-backed-auth-signal'
    readonly extractor: '@aihu/auth ScopeSignal layer reads cookie → getToken returns live value'
  }
}

JWT relay documentation artifact — describes where tokens originate in SSR and client contexts.

interface MagnaPluginOptions {
  /** Magna GraphQL endpoint URL (e.g., https://magna.example.com/graphql). */
  readonly url: string
  /** Path to the GraphQL SDL schema file. Default: 'schema.graphql'. */
  readonly schemaPath?: string
  /** Static headers merged into every request. */
  readonly headers?: Readonly<Record<string, string>>
  /** Git revision (informational; injected into build metadata). */
  readonly gitRev?: string
  /**
   * Getter for the current JWT. Called per-request.
   * Return null to omit the Authorization header entirely.
   */
  readonly getToken?: () => string | null
  /**
   * Custom fetch implementation. Defaults to globalThis.fetch.
   * Useful for testing or non-standard environments.
   */
  readonly fetch?: typeof globalThis.fetch
}

Configuration options for the magna GraphQL plugin.

interface MagnaSubscriptionHandle<T> {
  /** Current value signal. Always starts as null in the v0.1 shim. */
  readonly state: Signal<T | null>
  /** Idempotent close. No-op in v0.1. */
  readonly close: () => void
  /**
   * True when streaming is not available and the handle is a degraded fallback.
   * Always true in v0.1.
   */
  readonly degraded: boolean
}

Handle returned by `useMagnaSubscription`.

type MagnaFetch = <TData = unknown>(
  operation: string,
  variables?: Readonly<Record<string, unknown>>,
) => Promise<{
  readonly data: TData | null
  readonly errors?: ReadonlyArray<{ readonly message: string }>
}>

Typed fetch wrapper for Magna GraphQL operations.

type MagnaResource<T> = Resource<T>

Reactive resource handle wrapping a Magna GraphQL query.