### Configure Nikcio.UHeadless Services in Program.cs

Source: https://github.com/nikcio/nikcio.uheadless/blob/contrib/docs/src/content/docs/v6/fundamentals/getting-started.md

This C# code snippet demonstrates how to add Nikcio.UHeadless services to your Umbraco application's service collection. It includes default configurations and adds specific GraphQL queries. This should be placed within your `Program.cs` file during the Umbraco builder setup.

```csharp
using Nikcio.UHeadless;
using Nikcio.UHeadless.Defaults.ContentItems;

// ... inside Program.cs

builder.CreateUmbracoBuilder()
    .AddUHeadless(options =>
    {
        options.DisableAuthorization = true; // Change this later when adding authentication - See documentation

        options.AddDefaults();

        options.AddQuery<ContentByRouteQuery>();
        options.AddQuery<ContentByGuidQuery>();
    })
    .Build();
```

--------------------------------

### Configure Nikcio.UHeadless Services and Endpoint in Startup.cs

Source: https://github.com/nikcio/nikcio.uheadless/blob/contrib/docs/src/content/docs/v4/fundamentals/getting-started.md

Adds Nikcio.UHeadless services and configures the GraphQL endpoint in the Startup.cs file. The .AddUHeadless() method registers necessary services, and app.UseUHeadlessGraphQLEndpoint() sets up the GraphQL access point.

```csharp
using Nikcio.UHeadless.Extensions;

public void ConfigureServices(IServiceCollection services)
{
    services.AddUmbraco(_env, _config)
        /* Code omitted for clarity */
        .AddUHeadless()
        /* Code omitted for clarity */
}

public void Configure(IApplicationBuilder app, IWebHostEnvironment env)
{
    /* Code omitted for clarity */

    app.UseUHeadlessGraphQLEndpoint();

    app.UseUmbraco();
    /* etc... */
}
```

--------------------------------

### Add ContentByIdQuery to Nikcio.UHeadless

Source: https://github.com/nikcio/nikcio.uheadless/blob/contrib/docs/src/content/docs/v5/fundamentals/getting-started.md

Extends the Nikcio.UHeadless configuration in `Program.cs` to include the `ContentByIdQuery`. This enables querying content items using their numeric ID in addition to their GUID.

```csharp
.AddUHeadless(options =>
{
    // Existing configuration

    options.AddQuery<ContentByIdQuery>();
})
```

--------------------------------

### Add Custom ContentAll Query to Nikcio.UHeadless

Source: https://github.com/nikcio/nikcio.uheadless/blob/contrib/docs/src/content/docs/v4/fundamentals/getting-started.md

Extends Nikcio.UHeadless configuration in Startup.cs to include the 'contentAll' GraphQL query. This allows querying all content items, but note that it overrides default queries like 'contentAtRoot'.

```csharp
.AddUHeadless(new()
{
    UHeadlessGraphQLOptions = new()
    {
        GraphQLExtensions = (IRequestExecutorBuilder builder) =>
        {
            builder.UseContentQueries(); // Use this from v4.1.0+ (Only add one)
            builder.AddTypeExtension<BasicContentAllQuery>();
            return builder;
        },
    },
})
```

--------------------------------

### Install Dependencies with pnpm

Source: https://github.com/nikcio/nikcio.uheadless/blob/contrib/docs/README.md

Installs all necessary project dependencies using the pnpm package manager. This command should be run after cloning the project.

```sh
pnpm install
```

--------------------------------

### Configure UHeadless Extensions in UmbracoBuilder

Source: https://github.com/nikcio/nikcio.uheadless/blob/contrib/docs/src/content/docs/v8/fundamentals/getting-started.md

Add UHeadless services and default queries to the Umbraco builder configuration. This configures the GraphQL schema with content query capabilities and disables authorization for initial setup (should be enabled in production). Dependencies include AddUHeadless method and query types like ContentByRouteQuery and ContentByGuidQuery.

```csharp
builder.CreateUmbracoBuilder()
    // Default Umbraco configuration
    .AddUHeadless(options =>
    {
        options.DisableAuthorization = true; // Change this later when adding authentication - See documentation

        options.AddDefaults();

        options.AddQuery<ContentByRouteQuery>();
        options.AddQuery<ContentByGuidQuery>();
    })
    .Build();
```

--------------------------------

### GraphQL Query for All Content

Source: https://github.com/nikcio/nikcio.uheadless/blob/contrib/docs/src/content/docs/v4/fundamentals/getting-started.md

A sample GraphQL query to fetch all available content items using the 'contentAll' query. It retrieves the 'id' and 'name' for each content node.

```graphql
{
  contentAll {
    nodes {
      id
      name
    }
  }
}
```

--------------------------------

### Map Nikcio.UHeadless GraphQL Endpoint

Source: https://github.com/nikcio/nikcio.uheadless/blob/contrib/docs/src/content/docs/v7/fundamentals/getting-started.md

Maps the Nikcio.UHeadless GraphQL endpoint in your application's pipeline. It also configures the GraphQL IDE to be enabled only in development environments.

```csharp
await app.BootUmbracoAsync();

app.UseAuthentication();
app.UseAuthorization();

GraphQLEndpointConventionBuilder graphQLEndpointBuilder = app.MapUHeadless();

// Only enable the GraphQL IDE in development
if (!builder.Environment.IsDevelopment())
{
    graphQLEndpointBuilder.WithOptions(new GraphQLServerOptions()
    {
        Tool = 
        {
            Enable = false,
        }
    });
}

app.UseUmbraco()
    // Default Umbraco configuration
```

--------------------------------

### Add Required Namespaces in Program.cs

Source: https://github.com/nikcio/nikcio.uheadless/blob/contrib/docs/src/content/docs/v8/fundamentals/getting-started.md

Import the necessary namespaces for Nikcio.UHeadless configuration in your Umbraco Program.cs file. These namespaces provide access to the UHeadless extensions and default content item implementations.

```csharp
using Nikcio.UHeadless;
using Nikcio.UHeadless.Defaults.ContentItems;
```

--------------------------------

### Configure Program.cs for Nikcio.UHeadless Extensions

Source: https://github.com/nikcio/nikcio.uheadless/blob/contrib/docs/src/content/docs/v5/fundamentals/getting-started.md

Configures the Umbraco builder and application in `Program.cs` to enable Nikcio.UHeadless services and endpoints. This involves adding namespaces, calling `AddUHeadless` with options, and mapping the GraphQL endpoint. It also includes logic to disable the GraphQL IDE in non-development environments.

```csharp
using Nikcio.UHeadless;
using Nikcio.UHeadless.Defaults.ContentItems;

// ... inside Program.cs

builder.CreateUmbracoBuilder()
    .AddUHeadless(options =>
    {
        options.DisableAuthorization = true; // Change this later when adding authentication - See documentation

        options.AddDefaults();

        options.AddQuery<ContentByRouteQuery>();
        options.AddQuery<ContentByGuidQuery>();
    })
    .Build();

// ... later in the file

await app.BootUmbracoAsync();

app.UseAuthentication();
app.UseAuthorization();

GraphQLEndpointConventionBuilder graphQLEndpointBuilder = app.MapUHeadless();

// Only enable the GraphQL IDE in development
if (!builder.Environment.IsDevelopment())
{
    graphQLEndpointBuilder.WithOptions(new GraphQLServerOptions()
    {
        Tool =
        {
            Enable = false,
        }
    });
}

app.UseUmbraco()
    // Default Umbraco configuration
```

--------------------------------

### Start Local Development Server with pnpm

Source: https://github.com/nikcio/nikcio.uheadless/blob/contrib/docs/README.md

Starts a local development server, typically accessible at http://localhost:3000. This command is used for previewing changes during development.

```sh
pnpm run dev
```

--------------------------------

### Map Nikcio.UHeadless GraphQL Endpoint

Source: https://github.com/nikcio/nikcio.uheadless/blob/contrib/docs/src/content/docs/v6/fundamentals/getting-started.md

This C# code configures the application to use authentication and authorization, then maps the Nikcio.UHeadless GraphQL endpoint. It also includes logic to disable the GraphQL IDE in non-development environments. This should be placed after `app.BootUmbracoAsync()` in your `Program.cs` file.

```csharp
await app.BootUmbracoAsync();

app.UseAuthentication();
app.UseAuthorization();

GraphQLEndpointConventionBuilder graphQLEndpointBuilder = app.MapUHeadless();

// Only enable the GraphQL IDE in development
if (!builder.Environment.IsDevelopment())
{
    graphQLEndpointBuilder.WithOptions(new GraphQLServerOptions()
    {
        Tool =
        {
            Enable = false,
        }
    });
}

app.UseUmbraco()
    // Default Umbraco configuration
```

--------------------------------

### Install Nikcio.UHeadless Package

Source: https://github.com/nikcio/nikcio.uheadless/blob/contrib/docs/src/content/docs/v2/installation.md

Command to add the Nikcio.UHeadless NuGet package to your .NET project. This is the first step in integrating the package.

```bash
dotnet add Nikcio.UHeadless
```

--------------------------------

### Basic GraphQL Query for Content at Root

Source: https://github.com/nikcio/nikcio.uheadless/blob/contrib/docs/src/content/docs/v4/fundamentals/getting-started.md

A sample GraphQL query to fetch content items located at the root of the Umbraco CMS. It retrieves the 'id' and 'name' for each root content node.

```graphql
{
  contentAtRoot {
    nodes {
      id
      name
    }
  }
}
```

--------------------------------

### Example GraphQL Query for Content

Source: https://github.com/nikcio/nikcio.uheadless/blob/contrib/docs/src/content/docs/v2/installation.md

A sample GraphQL query to retrieve content from the root of your Umbraco site. This query fetches the ID and name for each content node at the root level, serving as a basic test for the UHeadless GraphQL endpoint.

```graphql
{
  contentAtRoot {
    nodes {
      id,
      name
    }
  }
}
```

--------------------------------

### GraphQL Query for Content by ID

Source: https://github.com/nikcio/nikcio.uheadless/blob/contrib/docs/src/content/docs/v5/fundamentals/getting-started.md

Example GraphQL query to fetch a content item from Umbraco using its numeric ID. This query is enabled after adding `ContentByIdQuery` to the Nikcio.UHeadless configuration.

```graphql
query {
  contentById(id: 1050) {
    id
    key
    name
    statusCode
    templateId
    updateDate
    url(urlMode: ABSOLUTE)
    urlSegment
  }
}
```

--------------------------------

### Setup UHeadless Environment with pnpm

Source: https://github.com/nikcio/nikcio.uheadless/blob/contrib/CONTRIBUTING.md

This command sets up the development environment for UHeadless using pnpm. It assumes Docker is running on the machine. This is the primary method for environment setup.

```bash
pnpm setup
```

--------------------------------

### Install Nikcio.UHeadless Add-On Package using .NET CLI

Source: https://github.com/nikcio/nikcio.uheadless/blob/contrib/docs/src/content/docs/v4/fundamentals/extend-uheadless.md

This command installs a specified Nikcio.UHeadless add-on package into your project. It requires the .NET CLI to be installed and accessible in your terminal. The command adds the package reference to your project file.

```shell
dotnet add [PackageName]
dotnet add Nikcio.UHeadless.Members
```

--------------------------------

### Install Nikcio.UHeadless Members Package

Source: https://github.com/nikcio/nikcio.uheadless/blob/contrib/docs/src/content/docs/v4/fundamentals/querying/members.md

Installs the necessary package for member queries in Nikcio.UHeadless. This is a prerequisite for using member query functionalities.

```shell
dotnet add Nikcio.UHeadless.Members
```

--------------------------------

### Nikcio.UHeadless Authentication and Authorization Setup

Source: https://github.com/nikcio/nikcio.uheadless/blob/contrib/docs/src/content/docs/v7/fundamentals/security.md

This section details the steps required to configure authentication and authorization in Nikcio.UHeadless, including service configuration and request pipeline setup.

```APIDOC
## Configure Services in `Program.cs`

### Description
Configure the `AddUHeadless` options in your `Program.cs` file to include authentication services. The `.AddAuth()` call should be the first configuration within the options.

### Method
C# Code Snippet

### Code
```csharp
.AddUHeadless(options =>
{
    options.AddAuth(new()
    {
        ApiKey = builder.Configuration.GetValue<string>("UHeadless:ApiKey") ?? throw new InvalidOperationException("No value for UHeadless:ApiKey was found"),
        Secret = builder.Configuration.GetValue<string>("UHeadless:Secret") ?? throw new InvalidOperationException("No value for UHeadless:Secret was found"),
    });

    // Other configuration
})
```

### Parameters
*   **ApiKey** (string) - Required - A value over 32 characters used in the `X-UHeadless-Api-Key` header for token creation.
*   **Secret** (string) - Required - A value over 64 characters used as the signing key for JWT tokens.

### Request Body
Not applicable (configuration via `appsettings.json` or environment variables is recommended).

### Response
Not applicable (configuration step).

---

## Configure Request Pipeline

### Description
Add `app.UseAuthentication();` and `app.UseAuthorization();` to your application's request pipeline after `app.BootUmbracoAsync()`.

### Method
C# Code Snippet

### Code
```csharp
app.UseAuthentication();
app.UseAuthorization();
```

### Response
Not applicable (configuration step).

---

## Create Token for GraphQL Queries

### Description
Once authentication is configured, default queries are protected and require a token. Generate a token by running a mutation against the `/graphql` endpoint.

### Method
GraphQL Mutation

### Endpoint
`/graphql`

### Parameters
#### Query Parameters
Not applicable.

#### Request Body
```graphql
mutation {
  createToken(claims: [
    {
      name: "headless-scope",
      value: "global.content.read"
    }
  ]) {
    expires
    header
    prefix
    token
  }
}
```

### Request Headers
*   **X-UHeadless-Api-Key** (string) - Required - The ApiKey value provided during configuration.

### Response
#### Success Response (200)
*   **expires** (integer) - The expiration timestamp of the token.
*   **header** (string) - The name of the header used for the token (e.g., `X-UHeadless-Token`).
*   **prefix** (string) - The prefix for the token (e.g., `Bearer `).
*   **token** (string) - The generated JWT token.

#### Response Example
```json
{
  "data": {
    "createToken": {
      "expires": 1717883090,
      "header": "X-UHeadless-Token",
      "prefix": "Bearer ",
      "token": "<TOKEN>"
    }
  }
}
```

---

## Query GraphQL Endpoint Using Token

### Description
Use the generated token, along with its prefix, in the appropriate header to authenticate GraphQL queries.

### Method
GraphQL Query

### Endpoint
`/graphql`

### Request Headers
*   **X-UHeadless-Token** (string) - Required - The token generated by the `createToken` mutation, including the prefix (e.g., `Bearer <TOKEN>`).

### Request Example
```graphql
query {
  contentByRoute(baseUrl: "", route: "/") {
    id
    key
    name
    statusCode
    templateId
    updateDate
    url(urlMode: ABSOLUTE)
    urlSegment
  }
}
```

### Response
#### Success Response (200)
*   **data** (object) - The result of the GraphQL query.

### Response Example
```json
{
  "data": {
    "contentByRoute": {
      "id": "...",
      "key": "...",
      "name": "...",
      "statusCode": 200,
      "templateId": "...",
      "updateDate": "...",
      "url": "...",
      "urlSegment": "..."
    }
  }
}
```

---

## Different Claims for Different Queries

### Description
Generate tokens with specific claims to control access to different queries. The `createToken` mutation supports adding multiple claims or a list of values for a single claim.

### Method
GraphQL Mutation

### Endpoint
`/graphql`

### Parameters
#### Query Parameters
Not applicable.

#### Request Body
**Option 1: Multiple claims**

```graphql
mutation {
  createToken(claims: [
    {
      name: "headless-scope",
      value: "global.content.read"
    },
    {
      name: "headless-scope",
      value: "global.media.read"
    }
  ]) {
    expires
    header
    prefix
    token
  }
}
```

**Option 2: List of values for a single claim**

```graphql
mutation {
  createToken(claims: [
    {
      name: "headless-scope",
      value: ["global.content.read", "global.media.read"]
    }
  ]) {
    expires
    header
    prefix
    token
  }
}
```

### Claim Values
*   **`global.content.read`**: Grants read access to content.
*   **`global.media.read`**: Grants read access to media.
*   **`property.values.member.picker`**: Required for accessing member picker editor data.
*   **`global.member.read`**: Grants read access to members.

Refer to the documentation for specific queries to determine the required claims.
```

--------------------------------

### Install Nikcio.UHeadless NuGet Package

Source: https://context7.com/nikcio/nikcio.uheadless/llms.txt

Installs the core Nikcio.UHeadless package using the .NET CLI. This is the first step to integrating headless capabilities into your Umbraco project.

```bash
dotnet add package Nikcio.UHeadless
```

--------------------------------

### Install Skybrud.Umbraco.Redirects Package

Source: https://github.com/nikcio/nikcio.uheadless/blob/contrib/docs/src/content/docs/v5/extending/skybrud-redirects.md

This command installs the Skybrud.Umbraco.Redirects NuGet package, which is a prerequisite for integrating redirects into your Umbraco Headless project.

```bash
Install-Package Skybrud.Umbraco.Redirects
```

--------------------------------

### Install NuGet Package

Source: https://github.com/nikcio/nikcio.uheadless/blob/contrib/docs/src/content/docs/v3/otherPackages/howToUseAExtendingPackage.md

Installs a specified package from NuGet into your project. This is the first step to integrating new functionality provided by an extending package.

```bash
dotnet add NAME_OF_PACKAGE
```

--------------------------------

### Install Skybrud.Umbraco.Redirects Package

Source: https://github.com/nikcio/nikcio.uheadless/blob/contrib/docs/src/content/docs/v7/extending/skybrud-redirects.md

Install the Skybrud.Umbraco.Redirects NuGet package to enable redirect management capabilities in your Umbraco Headless project.

```APIDOC
## Package Installation

### Description
Install the Skybrud.Umbraco.Redirects package via NuGet Package Manager.

### Command
```bash
Install-Package Skybrud.Umbraco.Redirects
```

### Version
- Recommended version: 13.0.4 or later

### Purpose
This package provides redirect management services required for integrating redirects with Nikcio.UHeadless content queries.
```

--------------------------------

### Query Media by GUID (GraphQL)

Source: https://context7.com/nikcio/nikcio.uheadless/llms.txt

Fetches media items using their GUID. It retrieves the name, URL, and properties, such as the Umbraco file path for images.

```graphql
query GetMediaByGuid {
  mediaByGuid(id: "a1b2c3d4-e5f6-7890-abcd-ef1234567890") {
    name
    url(urlMode: ABSOLUTE)
    properties {
      ... on Image {
        umbracoFile { value }
      }
    }
  }
}
```

--------------------------------

### ContentAll

Source: https://github.com/nikcio/nikcio.uheadless/blob/contrib/docs/src/content/docs/v4/fundamentals/querying/content.md

Gets all content items available.

```APIDOC
## ContentAll

### Description
Gets all the content items available.

### Method
GraphQL Query

### Endpoint
/graphql

### Parameters
- **culture** (string) - Optional - The culture.
- **preview** (boolean) - Optional - Fetch preview values. Preview will show unpublished items.
- **segment** (string) - Optional - The property variation segment.
- **fallback** (enum) - Optional - The property value fallback strategy.

### Request Example
```graphql
query {
  contentAll {
    // Content item fields
  }
}
```

### Response
#### Success Response (200)
- **contentItems** (array) - An array of content items.

#### Response Example
```json
{
  "data": {
    "contentAll": [
      {
        "id": "guid",
        "name": "string",
        // Other content item fields
      }
    ]
  }
}
```
```

--------------------------------

### Install UrlTracker Package using Package Manager Console

Source: https://github.com/nikcio/nikcio.uheadless/blob/contrib/docs/src/content/docs/v8/extending/url-tracker.md

Installs the UrlTracker package into your project via the Package Manager Console. This is a prerequisite for using UrlTracker functionalities within your UHeadless project. Ensure you are using a compatible version of UrlTracker as specified in the documentation.

```bash
Install-Package UrlTracker
```

--------------------------------

### Basic Member Queries Setup

Source: https://github.com/nikcio/nikcio.uheadless/blob/contrib/docs/src/content/docs/v4/fundamentals/querying/members.md

Configures the UHeadless options to include basic member queries. These queries do not require authorization.

```APIDOC
## Add Basic Member Queries

### Description
This code snippet demonstrates how to add basic member queries to your UHeadless configuration. These queries provide unrestricted access to member data.

### Method
Configuration Snippet

### Endpoint
N/A (Configuration)

### Parameters
#### Request Body
- **UHeadlessGraphQLOptions.GraphQLExtensions** (IRequestExecutorBuilder) - Required - A delegate to configure GraphQL extensions.
  - **builder.UseMemberQueries()** - Required - Enables member queries (v4.1.0+).
  - **builder.AddTypeExtension<BasicMembersAllQuery>()** - Required - Adds the specific query type extension.

### Request Example
```csharp
.AddUHeadless(new()
{
    UHeadlessGraphQLOptions = new()
    {
        GraphQLExtensions = (IRequestExecutorBuilder builder) =>
        {
            builder.UseMemberQueries(); // Use this from v4.1.0+ (Only add one)
            builder.AddTypeExtension<BasicMembersAllQuery>();
            return builder;
        },
    },
})
```

### Response
#### Success Response (200)
N/A (Configuration)

#### Response Example
N/A (Configuration)
```

--------------------------------

### AuthContentAtRootQuery

Source: https://github.com/nikcio/nikcio.uheadless/blob/contrib/docs/src/content/docs/v4/fundamentals/querying/content.md

Gets all content items at the root level. Requires authentication.

```APIDOC
## AuthContentAtRootQuery

### Description
Gets all the content items at the root level.

### Method
GraphQL Query

### Endpoint
/graphql

### Parameters
_(Parameters are the same as ContentAtRoot, but authentication is required)_

### Request Example
```graphql
query {
  authContentAtRoot {
    // Content item fields
  }
}
```

### Response
#### Success Response (200)
- **contentItems** (array) - An array of content items at the root.

#### Response Example
```json
{
  "data": {
    "authContentAtRoot": [
      {
        "id": "guid",
        "name": "string",
        // Other content item fields
      }
    ]
  }
}
```
```

--------------------------------

### Get Help with Astro CLI using pnpm

Source: https://github.com/nikcio/nikcio.uheadless/blob/contrib/docs/README.md

Displays help information for the Astro CLI. Use this command to understand available options and subcommands.

```sh
pnpm run astro -- --help
```

--------------------------------

### ContentByGuid

Source: https://github.com/nikcio/nikcio.uheadless/blob/contrib/docs/src/content/docs/v4/fundamentals/querying/content.md

Gets a content item by its GUID.

```APIDOC
## ContentByGuid

### Description
Gets a content item by GUID.

### Method
GraphQL Query

### Endpoint
/graphql

### Parameters
- **id** (string) - Required - The ID to fetch.
- **culture** (string) - Optional - The culture to fetch.
- **preview** (boolean) - Optional - Fetch preview values. Preview will show unpublished items.
- **segment** (string) - Optional - The property variation segment.
- **fallback** (enum) - Optional - The property value fallback strategy.

### Request Example
```graphql
query {
  contentByGuid(id: "guid") {
    // Content item fields
  }
}
```

### Response
#### Success Response (200)
- **contentItem** (object) - The content item with the specified GUID.

#### Response Example
```json
{
  "data": {
    "contentByGuid": {
      "id": "guid",
      "name": "string",
      // Other content item fields
    }
  }
}
```
```

--------------------------------

### Build Production Site with pnpm

Source: https://github.com/nikcio/nikcio.uheadless/blob/contrib/docs/README.md

Builds the project for production, outputting the static site files to the './dist/' directory. This command is used before deploying the site.

```sh
pnpm run build
```

--------------------------------

### ContentDescendantsByGuid

Source: https://github.com/nikcio/nikcio.uheadless/blob/contrib/docs/src/content/docs/v4/fundamentals/querying/content.md

Gets descendants on a content item selected by GUID.

```APIDOC
## ContentDescendantsByGuid

### Description
Gets descendants on a content item selected by GUID.

### Method
GraphQL Query

### Endpoint
/graphql

### Parameters
- **id** (string) - Required - The GUID to fetch descendants for.
- **culture** (string) - Optional - The culture.
- **preview** (boolean) - Optional - Fetch preview values. Preview will show unpublished items.
- **segment** (string) - Optional - The property variation segment.
- **fallback** (enum) - Optional - The property value fallback strategy.

### Request Example
```graphql
query {
  contentDescendantsByGuid(id: "guid") {
    // Content item fields
  }
}
```

### Response
#### Success Response (200)
- **contentItems** (array) - An array of content items that are descendants of the specified GUID.

#### Response Example
```json
{
  "data": {
    "contentDescendantsByGuid": [
      {
        "id": "guid",
        "name": "string",
        // Other content item fields
      }
    ]
  }
}
```
```

--------------------------------

### Preview Production Build Locally with pnpm

Source: https://github.com/nikcio/nikcio.uheadless/blob/contrib/docs/README.md

Previews the production build locally before deployment. This allows you to test the final output of your site.

```sh
pnpm run preview
```

--------------------------------

### AuthContentByGuidQuery

Source: https://github.com/nikcio/nikcio.uheadless/blob/contrib/docs/src/content/docs/v4/fundamentals/querying/content.md

Gets a content item by its GUID. Requires authentication.

```APIDOC
## AuthContentByGuidQuery

### Description
Gets a content item by GUID.

### Method
GraphQL Query

### Endpoint
/graphql

### Parameters
_(Parameters are the same as ContentByGuid, but authentication is required)_

### Request Example
```graphql
query {
  authContentByGuid(id: "guid") {
    // Content item fields
  }
}
```

### Response
#### Success Response (200)
- **contentItem** (object) - The content item with the specified GUID.

#### Response Example
```json
{
  "data": {
    "authContentByGuid": {
      "id": "guid",
      "name": "string",
      // Other content item fields
    }
  }
}
```
```

--------------------------------

### Configure UHeadless Services and Endpoint in startup.cs

Source: https://github.com/nikcio/nikcio.uheadless/blob/contrib/docs/src/content/docs/v2/installation.md

Demonstrates how to add UHeadless services and the GraphQL endpoint within the ConfigureServices and Configure methods of your startup.cs file. It highlights the key extension methods `.AddUHeadless()` and `app.UseUHeadlessGraphQLEndpoint()` which are essential for the package's functionality.

```csharp
using Nikcio.UHeadless.Extensions;

public void ConfigureServices(IServiceCollection services)
        {
            services.AddUmbraco(_env, _config)
                /* Code obmitted for clarity */
                .AddUHeadless()
                /* Code obmitted for clarity */
        }

public void Configure(IApplicationBuilder app, IWebHostEnvironment env)
{
    /* Code obmitted for clarity */

    app.UseUHeadlessGraphQLEndpoint();

    app.UseUmbraco()
    /* etc... */
}
```

--------------------------------

### AuthContentDescendantsByGuidQuery

Source: https://github.com/nikcio/nikcio.uheadless/blob/contrib/docs/src/content/docs/v4/fundamentals/querying/content.md

Gets descendants on a content item selected by GUID. Requires authentication.

```APIDOC
## AuthContentDescendantsByGuidQuery

### Description
Gets descendants on a content item selected by GUID.

### Method
GraphQL Query

### Endpoint
/graphql

### Parameters
_(Parameters are the same as ContentDescendantsByGuid, but authentication is required)_

### Request Example
```graphql
query {
  authContentDescendantsByGuid(id: "guid") {
    // Content item fields
  }
}
```

### Response
#### Success Response (200)
- **contentItems** (array) - An array of content items that are descendants of the specified GUID.

#### Response Example
```json
{
  "data": {
    "authContentDescendantsByGuid": [
      {
        "id": "guid",
        "name": "string",
        // Other content item fields
      }
    ]
  }
}
```
```

--------------------------------

### Configure UHeadless Services and Middleware in startup.cs

Source: https://github.com/nikcio/nikcio.uheadless/blob/contrib/docs/src/content/docs/v3/installation.md

Configures the necessary services and middleware for UHeadless within your ASP.NET Core application's startup.cs file. It involves adding UHeadless services and the GraphQL endpoint.

```csharp
using Nikcio.UHeadless.Extensions;

public void ConfigureServices(IServiceCollection services)
{
    services.AddUmbraco(_env, _config)
        /* Code obmitted for clarity */
        .AddUHeadless()
        /* Code obmitted for clarity */
}

public void Configure(IApplicationBuilder app, IWebHostEnvironment env)
{
    /* Code obmitted for clarity */

    app.UseUHeadlessGraphQLEndpoint();

    app.UseUmbraco()
    /* etc... */
}
```

--------------------------------

### GraphQL Query for Content by GUID

Source: https://github.com/nikcio/nikcio.uheadless/blob/contrib/README.md

An example GraphQL query to retrieve content items from Umbraco using their unique GUID. This demonstrates how to fetch basic content details such as ID, key, name, and URL.

```graphql
query {
  contentByGuid(id: "dcf18a51-6919-4cf8-89d1-36b94ce4d963") {
    id
    key
    name
    statusCode
    templateId
    updateDate
    url(urlMode: ABSOLUTE)
    urlSegment
  }
}
```

--------------------------------

### Project Structure Overview

Source: https://github.com/nikcio/nikcio.uheadless/blob/contrib/docs/README.md

Displays the typical directory and file structure of an Astro project integrated with Starlight. It shows where content, assets, and configuration files are located.

```tree
.\n├── public/\n├── src/\n│   ├── assets/\n│   ├── content/\n│   │   ├── docs/\n│   │   └── config.ts\n│   └── env.d.ts\n├── astro.config.mjs\n├── package.json\n└── tsconfig.json
```

--------------------------------

### Add Member Queries to UHeadless Options (C#)

Source: https://github.com/nikcio/nikcio.uheadless/blob/contrib/docs/src/content/docs/v5/fundamentals/querying/members.md

Demonstrates how to configure UHeadless options in C# to include specific member queries. This is essential for enabling these queries in your Umbraco CMS setup. It requires the Nikcio.UHeadless package to be installed.

```csharp
.AddUHeadless(options =>
{
    options.AddQuery<MemberByGuidQuery>();
})
```

--------------------------------

### Upgrade Starlight Integration with pnpm

Source: https://github.com/nikcio/nikcio.uheadless/blob/contrib/docs/README.md

Updates the Starlight integration package to the latest version using pnpm. This is recommended for receiving the latest features and bug fixes.

```sh
pnpm upgrade @astrojs/starlight --latest
```

--------------------------------

### Integrate Custom Content Queries in UHeadless Configuration (C#)

Source: https://github.com/nikcio/nikcio.uheadless/blob/contrib/docs/src/content/docs/v1/contentModels/editContentModels.md

This C# snippet configures the UHeadless GraphQL endpoint to include custom query extensions. It adds `CustomContentQuery`, `PropertyQuery`, and `MediaQuery` to maintain default functionality while incorporating custom types. This setup is crucial for activating the new content models.

```csharp
var graphQLExtensions = new List<Func<IRequestExecutorBuilder, IRequestExecutorBuilder>>
    {
        (builder) =>
        builder
            .AddTypeExtension<CustomContentQuery>()
            .AddTypeExtension<PropertyQuery>()
            .AddTypeExtension<MediaQuery>()
    };

services.AddUmbraco(_env, _config)
    .AddBackOffice()
    .AddWebsite()
    .AddComposers()
    .AddUHeadless(useSecuity: true, automapperAssemblies: new List<Assembly> { Assembly.GetAssembly(typeof(Startup)) }, graphQLExtensions: graphQLExtensions)
    .Build();
```

--------------------------------

### Configure Authentication and Authorization in Nikcio.UHeadless (C#)

Source: https://github.com/nikcio/nikcio.uheadless/blob/contrib/docs/src/content/docs/v4/fundamentals/security.md

This snippet demonstrates how to configure authentication and authorization for Nikcio.UHeadless by adding the necessary extensions in the `startup.cs` file. It involves modifying the `ConfigureServices` and `Configure` methods to include `AddAuthorization` and `UseAuthentication`/`UseAuthorization` middleware. Ensure authentication providers and policies are correctly set up.

```csharp
app.UseAuthentication();
app.UseAuthorization();
```

```csharp
.AddUHeadless(new()
{
    UHeadlessGraphQLOptions = new()
    {
        GraphQLExtensions = (IRequestExecutorBuilder builder) =>
        {
            builder.AddAuthorization();
            return builder;
        },
    }
})
```

--------------------------------

### Query Media by GUID

Source: https://context7.com/nikcio/nikcio.uheadless/llms.txt

Retrieves media item by its unique identifier (GUID). Supports URL mode specification and media type specific properties.

```APIDOC
## QUERY mediaByGuid

### Description
Retrieves media item by its unique identifier (GUID).

### Method
GET (GraphQL Query)

### Endpoint
/graphql

### Query Parameters
- **id** (string) - Required - The GUID of the media item
- **urlMode** (enum) - Optional - URL format mode: ABSOLUTE, RELATIVE

### Request Example
```graphql
query GetMediaByGuid {
  mediaByGuid(id: "a1b2c3d4-e5f6-7890-abcd-ef1234567890") {
    name
    url(urlMode: ABSOLUTE)
    properties {
      ... on Image {
        umbracoFile { value }
      }
    }
  }
}
```

### Response
#### Success Response (200)
- **name** (string) - The media item name
- **url** (string) - The media URL
- **properties** (object) - Media properties based on media type

#### Response Example
```json
{
  "data": {
    "mediaByGuid": {
      "name": "logo.png",
      "url": "https://mysite.com/media/logo.png",
      "properties": {
        "umbracoFile": { "value": "/media/logo.png" }
      }
    }
  }
}
```
```

--------------------------------

### Register GraphQL Extensions in Startup.cs

Source: https://github.com/nikcio/nikcio.uheadless/blob/contrib/docs/src/content/docs/v3/otherPackages/howToUseAExtendingPackage.md

Registers custom GraphQL queries, mutations, or subscriptions provided by extending packages within the `startup.cs` file. This configuration is crucial for making the new GraphQL schema elements available to your UHeadless API. Ensure you re-include default queries if overriding settings.

```csharp
public void ConfigureServices(IServiceCollection services) {
services.AddUmbraco(_env, _config)
    .AddBackOffice()
    .AddWebsite()
    .AddComposers()
    .AddUHeadless(new() {
        UHeadlessGraphQLOptions = new() {
            GraphQLExtensions = (IRequestExecutorBuilder builder) => {
                builder.AddMaxExecutionDepthRule(10);
                builder.AddTypeExtension<BasicContentQuery>();
                builder.AddTypeExtension<BasicPropertyQuery>();
                builder.AddTypeExtension<BasicMediaQuery>();
                return builder;
            },
        },
    })
    .Build();
}
```

--------------------------------

### ContentByGuidQuery

Source: https://github.com/nikcio/nikcio.uheadless/blob/contrib/docs/src/content/docs/v7/fundamentals/querying/content.md

Retrieves a single content item by its globally unique identifier (GUID). This query is useful for direct access to specific content when you have the GUID.

```APIDOC
## ContentByGuidQuery

### Description
Gets a content item by Guid.

### Query Class
ContentByGuidQuery

### Required Claim Values
- `content.by.guid.query`
- `global.content.read`

### Authorization
One of the required claim values must be present when authorization is enabled.

### Usage
```csharp
.AddUHeadless(options =>
{
    options.AddQuery<ContentByGuidQuery>();
})
```

### Access
Explore this query and its parameters in the GraphQL UI at `/graphql` after adding it to UHeadless options.
```

--------------------------------

### Configure UHeadless GraphQL Endpoint Options

Source: https://github.com/nikcio/nikcio.uheadless/blob/contrib/docs/src/content/docs/v4/reference/endpoint-options.md

Demonstrates how to configure the UHeadless GraphQL endpoint using `UHeadlessEndpointOptions` and `GraphQLServerOptions`. This example shows setting the GraphQL path and enabling the GraphQL tool.

```csharp
app.UseUHeadlessGraphQLEndpoint(new UHeadlessEndpointOptions
{
    CorsPolicy = null,
    GraphQLPath = "/graphql",
    GraphQLServerOptions = new()
    {
        Tool = {
            Enable = true
        }
    }
});
```

--------------------------------

### Configure Authentication and Authorization Services

Source: https://github.com/nikcio/nikcio.uheadless/blob/contrib/docs/src/content/docs/v6/fundamentals/security.md

This section details how to configure the authentication and authorization services in your `Program.cs` file for Nikcio.UHeadless. Ensure that `.AddAuth()` is called first within the `AddUHeadless` options.

```APIDOC
## Configure Authentication and Authorization Services

### Description
Configure the necessary services for authentication and authorization in your Nikcio.UHeadless application by modifying the `Program.cs` file.

### Method
```csharp
// In Program.cs
builder.Services.AddUHeadless(options =>
{
    options.AddAuth(new()
    {
        ApiKey = builder.Configuration.GetValue<string>("UHeadless:ApiKey") ?? throw new InvalidOperationException("No value for UHeadless:ApiKey was found"),
        Secret = builder.Configuration.GetValue<string>("UHeadless:Secret") ?? throw new InvalidOperationException("No value for UHeadless:Secret was found"),
    });

    // Other configuration
});

app.UseAuthentication();
app.UseAuthorization();
```

### Parameters

#### Request Body
*   **ApiKey** (string) - Required - A value over 32 characters used in the `X-UHeadless-Api-Key` header for token creation.
*   **Secret** (string) - Required - A value over 64 characters used as the signing key for JWT tokens.

### Notes
*   The `.AddAuth()` call must be the first configuration within the `AddUHeadless` options.
*   `ApiKey` and `Secret` can be loaded from `appsettings.json` or other configuration sources.
```

--------------------------------

### Authentication and Authorization Configuration

Source: https://github.com/nikcio/nikcio.uheadless/blob/contrib/docs/src/content/docs/v8/fundamentals/security.md

Configure services in `Program.cs` to enable authentication and authorization for Nikcio.UHeadless. This involves adding authentication services and setting up the request pipeline.

```APIDOC
## Configure Services in `Program.cs`

### Description
Configure the `AddUHeadless` options to include authentication services. Ensure `.AddAuth()` is called first within the options.

### Method
Configuration

### Endpoint
`Program.cs` (Configuration)

### Parameters
#### Request Body
- **options** (object) - Required - The options object for `AddUHeadless`.
  - **AddAuth**(authOptions) - Required - Configures authentication.
    - **authOptions** (object)
      - **ApiKey** (string) - Required - A key over 32 characters used for the `X-UHeadless-Api-Key` header.
      - **Secret** (string) - Required - A secret over 64 characters used as the JWT signing key.

### Request Example
```csharp
builder.Services.AddUHeadless(options =>
{
    options.AddAuth(new()
    {
        ApiKey = builder.Configuration.GetValue<string>("UHeadless:ApiKey") ?? throw new InvalidOperationException("No value for UHeadless:ApiKey was found"),
        Secret = builder.Configuration.GetValue<string>("UHeadless:Secret") ?? throw new InvalidOperationException("No value for UHeadless:Secret was found"),
    });

    // Other configuration
});

app.UseAuthentication();
app.UseAuthorization();
```

### Response
N/A (Configuration step)

### Error Handling
- Throws `InvalidOperationException` if `UHeadless:ApiKey` or `UHeadless:Secret` are not found in configuration.
```

--------------------------------

### Query Content by GUID

Source: https://context7.com/nikcio/nikcio.uheadless/llms.txt

Fetches content directly by its unique identifier (GUID) found in Umbraco backoffice Info tab. Supports culture-specific context and property type filtering.

```APIDOC
## QUERY contentByGuid

### Description
Fetches content directly by its unique identifier (found in Umbraco backoffice Info tab).

### Method
GET (GraphQL Query)

### Endpoint
/graphql

### Query Parameters
- **id** (string) - Required - The GUID of the content item (e.g., "dcf18a51-6919-4cf8-89d1-36b94ce4d963")
- **inContext.culture** (string) - Optional - The culture context for the query (e.g., "en-US")

### Request Example
```graphql
query GetContentByGuid {
  contentByGuid(
    id: "dcf18a51-6919-4cf8-89d1-36b94ce4d963"
    inContext: {
      culture: "en-US"
    }
  ) {
    id
    key
    name
    templateId
    updateDate
    url(urlMode: ABSOLUTE)
    properties {
      ... on HomePage {
        title { value }
        metaDescription { value }
      }
    }
  }
}
```

### Response
#### Success Response (200)
- **id** (string) - The content item ID
- **key** (string) - The content item GUID
- **name** (string) - The content item name
- **templateId** (string) - The template ID
- **updateDate** (date) - Last update timestamp
- **url** (string) - The content URL in specified format
- **properties** (object) - Content properties based on content type

#### Response Example
```json
{
  "data": {
    "contentByGuid": {
      "id": "1001",
      "key": "dcf18a51-6919-4cf8-89d1-36b94ce4d963",
      "name": "Home",
      "templateId": "template-1",
      "updateDate": "2024-01-15T10:30:00Z",
      "url": "https://mysite.com/",
      "properties": {
        "title": { "value": "Welcome to Our Site" },
        "metaDescription": { "value": "A great site" }
      }
    }
  }
}
```
```

--------------------------------

### Basic Content Queries

Source: https://github.com/nikcio/nikcio.uheadless/blob/contrib/docs/src/content/docs/v4/fundamentals/querying/content.md

This section outlines the available 'Basic' content queries in Nikcio.UHeadless, which do not require authorization. It includes examples of how to enable these queries and a list of all available query classes.

```APIDOC
## Basic Queries

### Description
Provides unrestricted access to CMS data without requiring authorization. These queries can be configured via the `UHeadlessGraphQLOptions.GraphQLExtensions`.

### Method
GET (typically via GraphQL endpoint)

### Endpoint
`/graphql`

### Parameters
#### Query Parameters
No direct query parameters are defined for the GraphQL endpoint itself. Parameters are defined within the GraphQL schema for each query.

#### Request Body
Not applicable for GET requests.

### GraphQL Schema Examples (Conceptual)

**Query:** `contentAtRoot`
**Description:** Gets all the content items at the root level.

**Query:** `content(id: ID!)`
**Description:** Gets a content item by its ID.

**Query:** `contentByGuid(guid: GUID!)`
**Description:** Gets a content item by its GUID.

### Available Basic Query Classes

- **`BasicContentAllQuery`**: Gets all the content items available.
- **`BasicContentAtRootQuery`**: Gets all the content items at the root level.
- **`BasicContentByAbsoluteRouteQuery`**: Gets a content item by an absolute route.
- **`BasicContentByContentTypeQuery`**: Gets all the content items by content type.
- **`BasicContentByGuidQuery`**: Gets a content item by GUID.
- **`BasicContentByIdQuery`**: Gets a content item by ID.
- **`BasicContentByTagQuery`**: Gets content items by tag.
- **`BasicContentDescendantsByAbsoluteRouteQuery`**: Gets content item descendants by an absolute route.
- **`BasicContentDescendantsByContentTypeQuery`**: Gets all descendants of content items with a specific content type.
- **`BasicContentDescendantsByGuidQuery`**: Gets descendants on a content item selected by GUID.
- **`BasicContentDescendantsByIdQuery`**: Gets descendants on a content item selected by ID.

### Request Example (Enabling Queries in C#)
```csharp
.AddUHeadless(new()
{
    UHeadlessGraphQLOptions = new()
    {
        GraphQLExtensions = (IRequestExecutorBuilder builder) =>
        {
            builder.UseContentQueries(); // Use this from v4.1.0+ (Only add one)
            builder.AddTypeExtension<BasicContentAllQuery>();
            builder.AddTypeExtension<BasicContentByIdQuery>();
            // Add other desired basic queries here
            return builder;
        },
    },
})
```

### Response Example (Conceptual GraphQL Response for `contentAtRoot`)
```json
{
  "data": {
    "contentAtRoot": [
      {
        "id": "1072",
        "name": "Home",
        "contentTypeAlias": "homePage"
      },
      {
        "id": "1073",
        "name": "About Us",
        "contentTypeAlias": "contentPage"
      }
    ]
  }
}
```
```

--------------------------------

### Query Content by GUID (GraphQL)

Source: https://context7.com/nikcio/nikcio.uheadless/llms.txt

Fetches content based on its unique GUID, which can be found in the Umbraco backoffice. This query specifies the desired fields, including ID, name, templateId, and properties for the homepage.

```graphql
query GetContentByGuid {
  contentByGuid(
    id: "dcf18a51-6919-4cf8-89d1-36b94ce4d963"
    inContext: {
      culture: "en-US"
    }
  ) {
    id
    key
    name
    templateId
    updateDate
    url(urlMode: ABSOLUTE)
    properties {
      ... on HomePage {
        title { value }
        metaDescription { value }
      }
    }
  }
}
```

--------------------------------

### GET /graphql - Utility Get Claim Groups Query

Source: https://github.com/nikcio/nikcio.uheadless/blob/contrib/docs/src/content/docs/v6/fundamentals/security.md

Retrieve all default claims and scopes used by queries in your application. This utility endpoint helps discover available claim groups and their values for development and debugging purposes.

```APIDOC
## GET /graphql - utility_GetClaimGroups

### Description
Query all default claims and scopes grouped by category (Members, Content, Media, etc.). This utility query is publicly accessible and intended for development purposes only.

### Method
GET (via GraphQL POST to /graphql endpoint)

### Query Registration
```csharp
.AddUHeadless(options =>
{
    options.AddQuery<UtilityClaimGroupsQuery>();
})
```

### GraphQL Query
```graphql
query {
  utility_GetClaimGroups {
    groupName
    claimValues {
      name
      values
    }
  }
}
```

### Response Fields
- **groupName** (string) - Category name (e.g., "Members", "Content", "Media")
- **claimValues** (array) - Array of claim configurations
  - **name** (string) - Claim name (e.g., "headless-scope")
  - **values** (array) - Array of available claim values/scopes

### Response Example
```json
{
  "data": {
    "utility_GetClaimGroups": [
      {
        "groupName": "Members",
        "claimValues": [
          {
            "name": "headless-scope",
            "values": [
              "property.values.member.picker",
              "global.member.read",
              "find.members.by.display.name.query",
              "find.members.by.email.query",
              "find.members.by.role.query",
              "find.members.by.username.query",
              "member.by.email.query",
              "member.by.guid.query",
              "member.by.id.query",
              "member.by.username.query"
            ]
          }
        ]
      },
      {
        "groupName": "Content",
        "claimValues": [
          {
            "name": "headless-scope",
            "values": [
              "content.by.route.query",
              "global.content.read",
              "content.by.contentType.query",
              "content.at.root.query",
              "content.by.id.query",
              "content.by.guid.query",
              "content.by.tag.query"
            ]
          }
        ]
      },
      {
        "groupName": "Media",
        "claimValues": [
          {
            "name": "headless-scope",
            "values": [
              "media.by.contentType.query",
              "global.media.read",
              "media.at.root.query",
              "media.by.id.query",
              "media.by.guid.query"
            ]
          }
        ]
      }
    ]
  }
}
```

### Security Note
This query is publicly accessible and should only be used for development purposes. Consider restricting access in production environments.
```

--------------------------------

### Add Content Query to UHeadless Options (C#)

Source: https://github.com/nikcio/nikcio.uheadless/blob/contrib/docs/src/content/docs/v5/fundamentals/querying/content.md

Demonstrates how to add a content query, specifically ContentByRouteQuery, to the UHeadless options during application startup. This is a prerequisite for using the query in your application.

```csharp
.AddUHeadless(options =>
{
    options.AddQuery<ContentByRouteQuery>();
})
```

--------------------------------

### Query Options Configuration

Source: https://github.com/nikcio/nikcio.uheadless/blob/contrib/docs/src/content/docs/v5/fundamentals/querying/members.md

This demonstrates how to add queries to the UHeadless options.

```APIDOC
```
.AddUHeadless(options =>
{
    options.AddQuery<MemberByGuidQuery>();
})
```
```

--------------------------------

### ContentByTag

Source: https://github.com/nikcio/nikcio.uheadless/blob/contrib/docs/src/content/docs/v4/fundamentals/querying/content.md

Gets content items by tag.

```APIDOC
## ContentByTag

### Description
Gets content items by tag.

### Method
GraphQL Query

### Endpoint
/graphql

### Parameters
- **tag** (string) - Required - The tag to fetch.

### Request Example
```graphql
query {
  contentByTag(tag: "featured") {
    // Content item fields
  }
}
```

### Response
#### Success Response (200)
- **contentItems** (array) - The content items with the specified tag.

#### Response Example
```json
{
  "data": {
    "contentByTag": [
      {
        "id": "guid",
        "name": "string",
        // Other content item fields
      }
    ]
  }
}
```
```

--------------------------------

### Run Astro CLI Commands with pnpm

Source: https://github.com/nikcio/nikcio.uheadless/blob/contrib/docs/README.md

Executes Astro Command Line Interface (CLI) commands, such as 'astro add' or 'astro check'. This is a versatile command for managing your Astro project.

```sh
pnpm run astro ...
```