pnwkit 3.0 - v4.3.0
    Preparing search index...

    Class BulletinsQuery<F, I>

    Query builder for fetching bulletin data from the Politics & War API.

    Create new instances using the factory method: pnwkit.queries.bulletins() Bulletins are announcements posted by nations and alliances.

    Features:

    • Type-safe field selection and filtering
    • Include author nation and alliance data
    • Filter by ID, date range, nation, alliance, type
    • Access to bulletin content and metadata
    • Pagination support
    // Get recent alliance bulletins
    const bulletins = await pnwkit.queries.bulletins()
      .select('id', 'headline', 'body', 'date', 'pinned')
      .where({ alliance_id: [123] })
      .first(50)
      .execute();
    // Type: { id: number, headline: string, body: string, date: string, pinned: boolean }[]

    // Query bulletins with author details
    const bulletins = await pnwkit.queries.bulletins()
      .select('id', 'headline', 'date')
      .include('nation', builder => builder
        .select('id', 'nation_name', 'alliance_id')
      )
      .where({ orderBy: [{ column: Enum('DATE'), order: Enum('DESC') }] })
      .execute();
    // Type: { id: number, headline: string, date: string, nation: {...} }[]

    Type Parameters

    • F extends readonly Exclude<keyof BulletinFields, "__typename">[] = []

      Selected field names

    • I extends Record<string, any> = {}

      Included relations

    Hierarchy

    • QueryBuilder<BulletinFields, BulletinQueryParams>
      • BulletinsQuery
    Index
    apiKeyOverride? filters queryName selectedFields skipCacheFlag subqueries MAX_ARRAY_SIZE MAX_FIELD_NAME_LENGTH MAX_FIELDS_PER_LEVEL MAX_NESTING_DEPTH MAX_QUERY_SIZE MAX_STRING_LENGTH QUERIES_WITHOUT_DATA_WRAPPER
    apiKey buildQuery execute include sanitizeString select serializeObject skipCache where
    apiKeyOverride?: string

    Per-call API key override, set via apiKey.

    filters: BulletinQueryParams = ...
    queryName: string = 'bulletins'
    selectedFields: (
        | "nation_id"
        | "id"
        | "type"
        | "alliance_id"
        | "date"
        | "headline"
        | "excerpt"
        | "image"
        | "body"
        | "author"
        | "pinned"
        | "like_count"
        | "replies_enabled"
        | "locked"
        | "edit_date"
        | "archived"
        | "replies"
    )[] = []
    skipCacheFlag: boolean = false

    When true, this call bypasses the response cache. Set via skipCache.

    subqueries: Map<string, SubqueryConfig<any, {}, Record<string, any>>> = ...
    MAX_ARRAY_SIZE: 1000
    MAX_FIELD_NAME_LENGTH: 100
    MAX_FIELDS_PER_LEVEL: 100
    MAX_NESTING_DEPTH: 10
    MAX_QUERY_SIZE: 50000
    MAX_STRING_LENGTH: 10000
    QUERIES_WITHOUT_DATA_WRAPPER: Set<string> = ...

    Queries that return data directly without wrapping in a 'data' object. These queries follow a different GraphQL schema structure.

    • Use a specific API key for this call instead of the client's default key.

      Parameters

      • key: string

        The Politics & War API key to authenticate this query with.

      Returns this

      This query builder instance for method chaining.

      await pnwkit.queries.nations()
        .select('id', 'nation_name')
        .apiKey('another-api-key')
        .execute();

    • Build the final GraphQL query string with comprehensive validation.

      Constructs a complete GraphQL query including:

      • Main fields and subqueries with proper formatting
      • Pagination variables (first, page)
      • Filter parameters with type-safe serialization
      • Optional paginator info fields

      Validation includes:

      • Field count limits (max 100 per level)
      • Field name format and length validation (max 100 chars)
      • Query size validation (max 50KB)
      • All filter values properly sanitized and escaped

      Parameters

      • includePaginator: boolean

        Whether to include pagination info in response

      Returns string

      Complete GraphQL query string ready for execution

      Error if field count/name/size limits exceeded or filters contain invalid values

    • Returns Promise<SelectFields<BulletinFields, F, I>[]>

    • Parameters

      • withPaginator: true

      Returns Promise<
          {
              data: SelectFields<BulletinFields, F, I>[];
              paginatorInfo: paginatorInfo;
          },
      >

    • Sanitize and escape a string value for safe GraphQL usage.

      Validates input type and length, checks for null bytes, and escapes special characters including backslashes, quotes, newlines, carriage returns, tabs, form feeds, and backspaces.

      Parameters

      • str: string

        The string to sanitize

      Returns string

      Sanitized string with all special characters properly escaped

      Error if input is not a string, exceeds maximum length (10KB), or contains null bytes

    • Select specific fields to retrieve from bulletins

      Type Parameters

      • const Fields extends readonly (
            | "nation_id"
            | "id"
            | "type"
            | "alliance_id"
            | "date"
            | "headline"
            | "excerpt"
            | "image"
            | "body"
            | "author"
            | "pinned"
            | "like_count"
            | "replies_enabled"
            | "locked"
            | "edit_date"
            | "archived"
            | "replies"
        )[]

      Parameters

      • ...fields: Fields

        Field names to select

      Returns BulletinsQuery<Fields>

      New query instance with selected fields

      Error if no fields are provided

      .select('id', 'headline', 'body', 'date', 'pinned')

    • Serialize an object to GraphQL format (enum values without quotes).

      Validates object structure and prevents prototype pollution by:

      • Using own properties only (not inherited)
      • Blocking dangerous keys (proto, constructor, prototype)
      • Validating GraphQL field name format
      • Validating enum value format (uppercase with underscores)
      • Ensuring numbers are finite (rejecting NaN, Infinity)

      Parameters

      • obj: Record<string, any>

        Plain object to serialize (not arrays)

      Returns string

      GraphQL-formatted object string in format {key:value, ...}

      Error if object is null/undefined/array, contains invalid field names, or has unsafe values

    • Bypass the response cache for this call.

      Only meaningful when caching is enabled on the client (cache.enabled). The result is fetched fresh from the API and is neither read from nor written to the cache. No effect when caching is disabled.

      Returns this

      This query builder instance for method chaining.

      await pnwkit.queries.nations()
        .select('id', 'nation_name')
        .skipCache()
        .execute();

    • Apply filters to the query

      Parameters

      • filters: BulletinQueryParams

        Query parameters for filtering results

      Returns this

      This query instance for method chaining

      .where({ alliance_id: [1234], after: '2026-01-01' })

    Settings
    Member Visibility

    On This Page
    Properties
    Methods