`installPluginPR` - API

installPluginPR() - Resolver

- - - installPluginPR.resolver.ts
    - installPluginPR.mutation.ts
    - installPluginPR.bridge.ts

installPluginPR() is a mutation resolver that allows you to add data from:

Async Functions during other resolver logic / GraphQL / API calls server-side
GraphQL - As a GraphQL mutation
API route (POST)
Clientside Hooks for calling the API with react-query from Web / Mobile

Resolver Config

Input / output types, defaults, schemas and general config for the installPluginPR() resolver are defined in its DataBridge file. Importable from:

import { installPluginPRBridge } from '@app/core/resolvers/installPluginPR.bridge'

Input Shape

You can find the schema used to validate the input arguments for the installPluginPR() resolver in the bridge config:

const InstallPluginPRInput = installPluginPRBridge.inputSchema

Show Input Schema

const InstallPluginPRInput = z.object({
    authKey: z
        .string()
        .nullish()
        .describe("Optionally provide the auth key of the user. Verifies whether authState can be trusted.")
        .sensitive() // = stripped in API responses, serverside only,
    authStamp: z
        .number()
        .int()
        .nullish()
        .describe("Optionally provide the auth stamp of the user. Verifies whether authState can be trusted.")
        .sensitive() // = stripped in API responses, serverside only,
    authState: z
        .object({
...
})
        .nullish()
        .describe("Optionally provide the auth state of the user. Only trusted if provided and verified by the server.")
        .sensitive() // = stripped in API responses, serverside only,
    repo: z
        .string()
        .describe("The target repository in the format \"owner/repo\""),
    baseBranch: z
        .string()
        .describe("The base branch for the pull request, e.g. \"main\" or \"develop\""),
    pluginBranch: z
        .string()
        .describe("The plugin branch to merge into the base branch, e.g. \"with/plugin-name\""),
    title: z
        .string()
        .optional()
        .describe("The title of the pull request"),
    body: z
        .string()
        .optional()
        .describe("The body of the pull request"),
})

💡 Could be handy to copy-paste into an AI chat?

If needed, you can extract the TypeScript type from the schema using z.input(), e.g.:

type InstallPluginPRInput = z.input<typeof InstallPluginPRInput>

Show Input Type

{
    /** Optionally provide the auth key of the user. Verifies whether authState can be trusted. */
    authKey?: (string | null) | undefined;
    /** Optionally provide the auth stamp of the user. Verifies whether authState can be trusted. */
    authStamp?: (number | null) | undefined;
    /** Optionally provide the auth state of the user. Only trusted if provided and verified by the server. */
    authState?: ({
        intent?: (("cliAuth" | "onboarding" | "forkStarter" | "dashboard") | null) | undefined;
        isSignedIn?: boolean;
        /** Whether the user is authenticated by their auth token */
        isAuthenticated?: boolean;
        /** Whether the user is authorized to access the premium starterkits */
        isAuthorized?: boolean;
        /** Whether the user has installed the FullProduct.dev GitHub App */
        isAppInstalled?: boolean;
        /** Whether the user has a customer id related to plan */
        isPlanOwner?: boolean;
        /** Whether the user is a member of an organisation plan */
        isPlanMember?: boolean;
        /** Whether the user is an admin of the currently active organisation */
        isPlanAdmin?: boolean;
        /** Whether the user as plan owner has a default organisation name */
        isDefaultOrgName?: boolean;
        /** Whether the user has an active subscription */
        isSubscription?: boolean;
        /** Whether the plan includes a lifetime license */
        hasLifetimeLicense?: boolean;
        /** Whether the user or organisation has made a private fork / clone of the starterkit yet */
        hasPrivateStarter?: boolean;
        /** Whether the currently active organisation has a private fork / clone of the starterkit */
        hasOrgStarter?: boolean;
        /** GitHub username */
        username?: (string | null) | undefined;
        /** Primary GitHub email */
        email?: (string | null) | undefined;
        /** GitHub avatar URL */
        avatar?: (string | null) | undefined;
        /** Clerk user id */
        userId?: (string | null) | undefined;
        sessionId?: (string | null) | undefined;
        /** GitHub App installation id */
        installationId?: (number | null) | undefined;
        /** GitHub App installation id for the current organisation */
        orgInstallationId?: (number | null) | undefined;
        /** Current organisation id */
        currentOrgId?: (string | null) | undefined;
        currentOrgName?: (string | null) | undefined;
        currentOrgGitHubSlug?: (string | null) | undefined;
        currentOrgGitHubUrl?: (string | null) | undefined;
        currentPlanId?: (string | null) | undefined;
        /** Type of plan the user is on */
        planType?: (("solo" | "startup" | "studio" | "subscription") | null) | undefined;
        seatsTotal?: (number | null) | undefined;
        seatsTaken?: (number | null) | undefined;
        seatsAvailable?: (number | null) | undefined;
        /** Date when the user's access to the premium starterkits ends */
        accessPeriodEndDate?: (Date | null) | undefined;
        /** Number of days remaining in the user's access period */
        accessPeriodDaysRemaining?: (number | null) | undefined;
        authToken?: (string | null) | undefined;
        cliToken?: (string | null) | undefined;
        githubToken?: (string | null) | undefined;
        repoAccess?: (string[] | null) | undefined;
        user?: ({
            /** Provided or auto-generated UUID (V4) */
            id?: string;
            /** Creation date */
            createdAt?: Date;
            /** Last modified date */
            modifiedAt?: Date;
            /** Mongoose version key */
            __v?: number;
            /** Auth provider sub or user ID */
            userId: string;
            /** Github username as Github is the only auth provider */
            username: string;
            /** Primary Github email used during OAuth */
            email: string;
            /** Github avatar URL */
            avatar: string | null;
            /** Github App installation ID */
            installationId: number | null;
            /** List of starter repos the user has access to, both official and private forks */
            repoAccess?: string[];
            /** Whether the user has access to any starter repos */
            isCliAuthorized?: boolean;
            /** Whether the user has access to the core repo */
            isCoreAuthorized?: boolean;
            /** Whether the user has a customer ID related to a plan */
            isPlanOwner?: boolean;
            /** Whether the user is a member of an organisation plan */
            isPlanMember?: boolean;
            /** Payment customer ID */
            customerId?: (string | null) | undefined;
            /** Payment subscription ID */
            subscriptionId?: (string | null) | undefined;
            /** Clerk org ID the user created */
            ownedOrgId?: (string | null) | undefined;
            /** Clerk org ID the user currently has active in the UI */
            currentOrgId?: (string | null) | undefined;
        } | null) | undefined;
        completedSteps?: (("createAccount" | "signIn" | "installApp" | "purchaseAccess" | "acceptInvite" | "createPrivateStarter" | "renameTeam" | "none")[] | null) | undefined;
        nextSteps?: (("createAccount" | "signIn" | "installApp" | "purchaseAccess" | "acceptInvite" | "createPrivateStarter" | "renameTeam" | "none")[] | null) | undefined;
        nextStep?: (("createAccount" | "signIn" | "installApp" | "purchaseAccess" | "acceptInvite" | "createPrivateStarter" | "renameTeam" | "none") | null) | undefined;
    } | null) | undefined;
    /** The target repository in the format "owner/repo" */
    repo: string;
    /** The base branch for the pull request, e.g. "main" or "develop" */
    baseBranch: string;
    /** The plugin branch to merge into the base branch, e.g. "with/plugin-name" */
    pluginBranch: string;
    /** The title of the pull request */
    title?: string | undefined;
    /** The body of the pull request */
    body?: string | undefined;
}

💡 Could be handy to copy-paste into an AI chat?

Output Shape

You can find the schema used to provide output defaults for the installPluginPR() resolver in the bridge config too:

const InstallPluginPROutput = installPluginPRBridge.outputSchema

Show Output Schema

const InstallPluginPROutput = z.object({
    isSignedIn: z
        .boolean()
        .optional(),
    isAuthenticated: z
        .boolean()
        .optional(),
    isAuthorized: z
        .boolean()
        .optional(),
    isAppInstalled: z
        .boolean()
        .optional(),
    username: z
        .string()
        .nullish(),
    repoAccess: z
        .array(z.string())
        .nullish(),
    repo: z
        .string()
        .default("codinsonn/green-stack-starter"),
    repoOwner: z
        .string()
        .nullish(),
    repoName: z
        .string()
        .nullish(),
    pluginBranches: z
        .array(z.string())
        .nullish(),
    pluginPRs: z
        .record(z.string(), PluginPR)
        .nullish(),
    error: z
        .string()
        .nullish(),
    prUrl: z
        .string()
        .url()
        .optional()
        .describe("The URL of the created or updated pull request"),
    prNumber: z
        .number()
        .optional()
        .describe("The number of the created or updated pull request"),
})

💡 Could be handy to copy-paste into an AI chat?

Here too, you can extract the TypeScript type from the schema using z.output(), e.g.:

type InstallPluginPROutput = z.output<typeof InstallPluginPROutput>

Show Output Type

{
    isSignedIn?: boolean;
    isAuthenticated?: boolean;
    isAuthorized?: boolean;
    isAppInstalled?: boolean;
    username?: (string | null) | undefined;
    repoAccess?: (string[] | null) | undefined;
    repo?: string;
    repoOwner?: (string | null) | undefined;
    repoName?: (string | null) | undefined;
    pluginBranches?: (string[] | null) | undefined;
    pluginPRs?: ({
        [x: string]: {
            id: number;
            number: number;
            title: string;
            body: string;
            branchName: string;
            baseBranch: string;
            url: string;
            diffUrl: string;
            pluginType: string;
        };
    } | null) | undefined;
    error?: (string | null) | undefined;
    /** The URL of the created or updated pull request */
    prUrl?: string | undefined;
    /** The number of the created or updated pull request */
    prNumber?: number | undefined;
}

💡 Could be handy to copy-paste into an AI chat?

Server Usage

`installPluginPR()` function

import { installPluginPR } from '@app/core/resolvers/installPluginPR.resolver'

// ... Later, in resolver or script logic ...
const output = await installPluginPR({ ...inputArgs })
//     ?^ InstallPluginPROutput

Note that using resolvers like installPluginPR() as async functions is only available server-side, and might cause issues if imported into the client bundle. For client-side usage, use any of the other options below.

GraphQL Mutation

`installPluginPRMutation()`

import { installPluginPRMutation } from '@app/core/resolvers/installPluginPR.mutation'

installPluginPRMutation() is a universal GraphQL mutation fetcher function.
It wil query the installPluginPR resolver for you as a GraphQL mutation:

const response = await installPluginPRMutation({ installPluginPRArgs: { ...inputArgs } })
//       ?^ { installPluginPR: InstallPluginPROutput }

Just make sure the installPluginPRArgs input matches the InstallPluginPRInput schema.

If you prefer, you can also use the following GraphQL snippet in your own GraphQL fetching logic:

GraphQL Mutation Snippet

query installPluginPR($installPluginPRArgs: InstallPluginPRInput!) {
    installPluginPR(args: $installPluginPRArgs) {
        isSignedIn
        isAuthenticated
        isAuthorized
        isAppInstalled
        username
        repoAccess
        repo
        repoOwner
        repoName
        pluginBranches
        pluginPRs {
            id
            number
            title
            body
            branchName
            baseBranch
            url
            diffUrl
            pluginType
        }
        error
        prUrl
        prNumber
    }
}

Custom Mutation

Using a custom query, you can omit certain fields you don’t need and request only what’s necessary.

If you do, we suggest using graphqlQuery(), as it works seamlessly on the server, browser and mobile app:

import { graphql } from '@app/core/graphql/graphql'
import { graphqlQuery } from '@app/core/graphql/graphqlQuery'
 
const query = graphql(`
    query installPluginPR($installPluginPRArgs: InstallPluginPRInput!) {
        installPluginPR(args: $installPluginPRArgs) {
            // -i- ... type hints for the fields you need ... -i-
        }
    }
`)
 
const response = await graphqlQuery(query, { installPluginPRArgs: { ...inputArgs } })
//       ?^ { installPluginPR: InstallPluginPROutput }

Just make sure the installPluginPRArgs input matches the InstallPluginPRInput schema.

Next.js API Route

`POST` requests

POST /api/plugins/pullrequests/install

Provide the request body as JSON (e.g. { "someArg": 123 }).

Make sure the params / body input match the InstallPluginPRInput schema.

Client Usage

Custom `react-query` hook

e.g. In the installPluginPR.mutation.ts file:

import { useMutation, UseMutationOptions, MutationKey } from '@tanstack/react-query'

 
export const useInstallPluginPRMutation = (
    options?: Omit<
        UseMutationOptions<InstallPluginPRMutationOutput, unknown, InstallPluginPRMutationInput>,
        'mutationFn' | 'mutationKey'
    > & { mutationKey?: MutationKey }
) => {
    return useMutation({
        mutationKey: ['installPluginPRMutation'],
        mutationFn: (input: InstallPluginPRMutationInput) => installPluginPRMutation(input),
        ...options,
    })
}

Be sure to check the useMutation docs for all the available options you might want to prefill or abstract.

Usage in React

import { useInstallPluginPRMutation } from '@app/core/resolvers/installPluginPR.mutation'

const { data, error, isLoading, mutateAsync } = useInstallPluginPRMutation({
    // ... any additional options ...
})

const onSubmit = async (input: InstallPluginPRInput) => {
    const response = await mutateAsync({ installPluginPRArgs: input }, options)
    //      ?^ { installPluginPR: InstallPluginPROutput } 
}

Be sure to check the useMutation docs for all the available options.

Usage - Form State

You can also use the installPluginPR input schema for react form state helpers, e.g.:

- - - useInstallPluginPRFormState.ts

import { z } from '@green-stack/schemas'
import { useFormState } from '@green-stack/forms/useFormState'
import { installPluginPRBridge } from '../resolvers/installPluginPR.bridge'
 
/* --- Types ----------------------------------------------------------------------------------- */
 
const { inputSchema: InstallPluginPRInput } = installPluginPRBridge
 
export const InstallPluginPRFormData = InstallPluginPRInput.extendSchema('InstallPluginPRFormData', {})
 
export type InstallPluginPRFormData = z.input<typeof InstallPluginPRFormData>
 
/** --- useInstallPluginPRFormState() ---------------------------------------------------------- */
/** -i- Form hook for the installPluginPR() resolver input */
export const useInstallPluginPRFormState = (options: {
    initialValues?: Partial<InstallPluginPRFormData>,
    validateOnChange?: boolean,
    validateOnBlur?: boolean,
    syncFromPropsKey?: string,
} = {}) => {
    return useFormState(InstallPluginPRFormData, options)
}

Check out the Form Management Docs for more details on how to use this hook.

Other

Disclaimer - Automatic Docgen

🤖

These dynamic API docs were auto-generated with npm run regenerate-docs. This happens from .bridge.ts files in any /resolvers/ folder.

You can opt-out of this by adding export const optOut = true somewhere in the file.

CheckList healthCheck

installPluginPR - API

installPluginPR() - Resolver

Resolver Config

Input Shape

Output Shape

Server Usage

installPluginPR() function

GraphQL Mutation

installPluginPRMutation()

GraphQL Mutation Snippet

Custom Mutation

Next.js API Route

POST requests

Client Usage

Custom react-query hook

Usage in React

Usage - Form State

Other

Disclaimer - Automatic Docgen

`installPluginPR` - API

`installPluginPR()` function

`installPluginPRMutation()`

`POST` requests

Custom `react-query` hook