tessl/npm-aws-amplify--api

A unified API layer for AWS Amplify that combines GraphQL and REST API functionality

—

Pending

Quality

Pending

Does it follow best practices?

Impact

Pending

No eval scenarios have been run

Securityby

Pending

The risk profile of this skill

Overview

Eval results

Files

GraphQL Client

Name: tessl/npm-aws-amplify--api
Author: tessl

Core GraphQL functionality for creating type-safe clients that work with Amplify data models or raw GraphQL operations.

Capabilities

Generate Client

Creates a GraphQL client that can work with models or raw GraphQL operations.

/**
 * Generates an API client that can work with models or raw GraphQL
 * @param options - Optional client configuration
 * @returns V6Client instance with GraphQL capabilities
 * @throws Error when client cannot be generated due to configuration issues
 */
function generateClient<
  T extends Record<any, any> = never,
  Options extends CommonPublicClientOptions = DefaultCommonClientOptions
>(options?: Options): V6Client<T, Options>;

interface CommonPublicClientOptions {
  authMode?: GraphQLAuthMode;
  authToken?: string;
  userAgentSuffix?: string;
  apiEndpoint?: string;
  region?: string;
  libraryConfigHeaders?: () => Record<string, string> | Record<string, string>;
}

type DefaultCommonClientOptions = {};

Usage Examples:

import { generateClient } from "@aws-amplify/api";
import type { Schema } from "./amplify/data/resource";

// Generate client with model support
const client = generateClient<Schema>();

// Use with models
const { data: todos, errors } = await client.models.Todo.list();
const { data: newTodo } = await client.models.Todo.create({
  content: "Learn GraphQL",
  completed: false,
});

// Generate client for raw GraphQL
const rawClient = generateClient();
const result = await rawClient.graphql({
  query: `query ListTodos { listTodos { items { id content } } }`,
});

// Generate client with custom auth mode
const clientWithAuth = generateClient({
  authMode: "userPool"
});

V6Client Interface

The main client interface providing GraphQL operations and utility methods.

interface V6Client<T, Options = DefaultCommonClientOptions> {
  /**
   * Execute GraphQL operations (queries, mutations, subscriptions)
   */
  graphql<FALLBACK_TYPES = unknown, TYPED_GQL_STRING = string>(
    options: GraphQLOptionsV6<FALLBACK_TYPES, TYPED_GQL_STRING>,
    additionalHeaders?: CustomHeaders
  ): GraphQLResponse<FALLBACK_TYPES, TYPED_GQL_STRING>;

  /**
   * Cancel a pending promise-based operation
   * @param promise - The promise to cancel
   * @param message - Optional cancellation message
   * @returns boolean indicating if cancellation was successful
   */
  cancel(promise: Promise<any>, message?: string): boolean;

  /**
   * Check if an error is from request cancellation
   * @param error - Error to check
   * @returns boolean indicating if error is from cancellation
   */
  isCancelError(error: any): boolean;

  /**
   * Model-specific operations (when T is provided)
   */
  models: T extends Record<any, any> ? ModelOperations<T> : never;
}

GraphQL Operations

Core GraphQL operation types and interfaces.

interface GraphQLOptionsV6<FALLBACK_TYPES = unknown, TYPED_GQL_STRING = string> {
  query: TYPED_GQL_STRING;
  variables?: Record<string, any>;
  authMode?: GraphQLAuthMode;
  authToken?: string;
}

type GraphQLResponse<FALLBACK_TYPES, TYPED_GQL_STRING> = 
  TYPED_GQL_STRING extends GraphQLQuery<infer T> 
    ? Promise<GraphQLResult<T>>
    : TYPED_GQL_STRING extends GraphQLSubscription<infer T>
      ? Observable<GraphQLResult<T>>
      : Promise<GraphQLResult<FALLBACK_TYPES>>;

enum GraphQLAuthMode {
  API_KEY = "apiKey",
  AWS_IAM = "iam", 
  AMAZON_COGNITO_USER_POOLS = "userPool",
  OPENID_CONNECT = "oidc",
  AWS_LAMBDA = "lambda",
  NONE = "none"
}

Model Operations

When using the client with a typed schema, model-specific operations become available.

type ModelOperations<T> = {
  [K in keyof T]: {
    /**
     * Create a new record
     */
    create(input: CreateInput<T[K]>): Promise<GraphQLResult<T[K]>>;
    
    /**
     * Get a record by identifier
     */
    get(input: GetInput<T[K]>): Promise<GraphQLResult<T[K] | null>>;
    
    /**
     * Update an existing record
     */
    update(input: UpdateInput<T[K]>): Promise<GraphQLResult<T[K]>>;
    
    /**
     * Delete a record
     */
    delete(input: DeleteInput<T[K]>): Promise<GraphQLResult<T[K]>>;
    
    /**
     * List records with optional filtering
     */
    list(input?: ListInput<T[K]>): Promise<GraphQLResult<ListResult<T[K]>>>;
    
    /**
     * Subscribe to create events
     */
    onCreate(options?: SubscriptionOptions): Observable<GraphQLResult<T[K]>>;
    
    /**
     * Subscribe to update events  
     */
    onUpdate(options?: SubscriptionOptions): Observable<GraphQLResult<T[K]>>;
    
    /**
     * Subscribe to delete events
     */
    onDelete(options?: SubscriptionOptions): Observable<GraphQLResult<T[K]>>;
  };
};

interface ListResult<T> {
  items: T[];
  nextToken?: string;
}

Error Handling

GraphQL-specific error types and handling.

interface GraphQLError {
  message: string;
  locations?: Array<{
    line: number;
    column: number;
  }>;
  path?: Array<string | number>;
  extensions?: Record<string, any>;
}

/**
 * Authentication error types for GraphQL operations
 */
enum GraphQLAuthError {
  NO_API_KEY = "NO_API_KEY",
  NO_CURRENT_USER = "NO_CURRENT_USER",
  NO_CREDENTIALS = "NO_CREDENTIALS", 
  NO_FEDERATED_JWT = "NO_FEDERATED_JWT",
  NO_AUTH_TOKEN = "NO_AUTH_TOKEN"
}

Custom Headers

Support for custom request headers in GraphQL operations.

type CustomHeaders = Record<string, string> | (() => Record<string, string>);

/**
 * Additional headers can be provided to GraphQL operations
 * Either as a static object or a function that returns headers
 */
interface CustomHeadersOptions {
  /**
   * Static headers object
   */
  headers?: Record<string, string>;
  
  /**
   * Function that returns headers (useful for dynamic auth tokens)
   */
  libraryConfigHeaders?: () => Record<string, string>;
}