@graphql-tools/federation/typings/managed-federation.d.ts

Useful tools to create and manipulate GraphQL schemas.

import { GraphQLSchema } from 'graphql';
import type { FetchFn } from '@graphql-tools/executor-http';
import { GetStitchedSchemaFromSupergraphSdlOpts } from './supergraph.js';
import { EventEmitter } from './utils.js';
export type FetchSupergraphSdlFromManagedFederationOpts = {
    /**
     * The graph ref of the managed federation graph.
     * It is composed of the graph ID and the variant (`<YOUR_GRAPH_ID>@<VARIANT>`).
     *
     * If not provided, `APOLLO_GRAPH_REF` environment variable is used.
     *
     * You can find a a graph's ref at the top of its Schema Reference page in Apollo Studio.
     */
    graphRef?: string;
    /**
     * The API key to use to authenticate with the managed federation up link.
     * It needs at least the `service:read` permission.
     *
     * If not provided, `APOLLO_KEY` environment variable will be used instead.
     *
     * [Learn how to create an API key](https://www.apollographql.com/docs/federation/v1/managed-federation/setup#4-connect-the-gateway-to-studio)
     */
    apiKey?: string;
    /**
     * The URL of the managed federation up link. When retrying after a failure, you should cycle through the default up links using this option.
     *
     * Uplinks are available in `DEFAULT_UPLINKS` constant.
     *
     * This options can also be defined using the `APOLLO_SCHEMA_CONFIG_DELIVERY_ENDPOINT` environment variable.
     * It should be a comma separated list of up links, but only the first one will be used.
     *
     * Default: 'https://uplink.api.apollographql.com/' (Apollo's managed federation up link on GCP)
     *
     * Alternative: 'https://aws.uplink.api.apollographql.com/' (Apollo's managed federation up link on AWS)
     */
    upLink?: string;
    /**
     * The ID of the last fetched supergraph.
     * If provided, a supergraph is returned only if the managed supergraph have changed.
     */
    lastSeenId?: string;
    /**
     * The fetch implementation to use.
     * Default: global.fetch
     */
    fetch?: FetchFn;
    /**
     * Up link can send back messages meant to be logged alongside the supergraph SDL.
     * By default, the console is used.
     */
    loggerByMessageLevel?: typeof DEFAULT_MESSAGE_LOGGER;
};
export type RouterConfig = {
    /**
     * The supergraph SDL.
     */
    supergraphSdl: string;
    /**
     * The minimum delay in seconds to wait before trying to fetch this supergraph again.
     */
    minDelaySeconds: number;
    /**
     * The ID of the supergraph. Should be used as `lastSeenId` in the next fetch.
     */
    id: string;
};
export type Unchanged = {
    /**
     * The minimum delay in seconds to wait before trying to fetch this supergraph again.
     */
    minDelaySeconds: number;
    /**
     * The ID of the supergraph. Should be used as `lastSeenId` in the next fetch.
     */
    id: string;
};
export type FetchError = {
    /**
     * The fetch error reported by the up link. This means it's not the local fetch error.
     * Local fetch errors are thrown as exceptions.
     */
    error: {
        code: string;
        message: string;
    };
    /**
     * The minimum delay in seconds to wait before trying to fetch this supergraph again.
     */
    minDelaySeconds: number;
};
/**
 * The default managed federation up links. In case of failure, you should try to cycle through these up links.
 *
 * The first one is Apollo's managed federation up link on GCP, the second one is on AWS.
 */
export declare const DEFAULT_UPLINKS: string[];
/**
 * Fetches the supergraph SDL from a managed federation GraphOS up link.
 * @param options
 * @throws When the fetch fails or the response is not a valid.
 * @returns An object with the supergraph SDL when possible. It also includes metadata to handle polling and retry logic.
 *
 *          If `lastSeenId` is provided and the supergraph has not changed, `supergraphSdl` is not present.
 *
 *          If The up link report a fetch error (which is not a local fetch error), it will be returned along with polling/retry metadata.
 *          Any local fetch error will be thrown as an exception.
 */
export declare function fetchSupergraphSdlFromManagedFederation(options?: FetchSupergraphSdlFromManagedFederationOpts): Promise<RouterConfig | Unchanged | FetchError>;
export type GetStitchedSchemaFromManagedFederationOpts = FetchSupergraphSdlFromManagedFederationOpts & Omit<GetStitchedSchemaFromSupergraphSdlOpts, 'supergraphSdl'>;
export type RouterConfigWithSchema = RouterConfig & {
    /**
     * The stitched schema based on the supergraph SDL.
     */
    schema: GraphQLSchema;
};
/**
 * Fetches the supergraph SDL from a managed federation GraphOS up link and stitches it into an executable schema.
 * @param options
 * @throws When the fetch fails, the response is not a valid or the stitching fails.
 * @returns An object with the supergraph SDL and the stitched schema when possible. It also includes metadata to handle polling and retry logic.
 *
 *          If `lastSeenId` is provided and the supergraph has not changed, `supergraphSdl` is not present.
 *
 *          If The up link report a fetch error (which is not a local fetch error), it will be returned along with polling/retry metadata.
 *          Any local fetch error will be thrown as an exception.
 */
export declare function getStitchedSchemaFromManagedFederation(options: GetStitchedSchemaFromManagedFederationOpts): Promise<RouterConfigWithSchema | FetchError | Unchanged>;
declare const DEFAULT_MESSAGE_LOGGER: {
    ERROR: (message: string) => void;
    WARN: (message: string) => void;
    INFO: (message: string) => void;
};
export type SupergraphSchemaManagerOptions = Omit<GetStitchedSchemaFromManagedFederationOpts, 'lastSeenId'> & {
    maxRetries?: number;
    minDelaySeconds?: number;
    retryDelaySeconds?: number;
};
export declare class SupergraphSchemaManager extends EventEmitter<{
    schema: [GraphQLSchema];
    error: [FetchError | unknown];
    failure: [FetchError | unknown];
    log: [{
        source: 'uplink' | 'manager';
        message: string;
        level: 'error' | 'warn' | 'info';
    }];
}> {
    #private;
    private options;
    schema?: GraphQLSchema;
    constructor(options: SupergraphSchemaManagerOptions);
    start(): void;
    forcePull(): void;
    stop(): void;
}
export {};