attio 0.0.1-experimental.20241008.2 → 0.0.1-experimental.20241010.1

package/lib/api/add-connection-definition.js

@@ -7,14 +7,13 @@ const addConnectionSchema = z.object({
     app_id: z.string(),
     connection_definition_id: z.string(),
 });
-export async function addConnectionDefinition({ token, devSlug, appId, key, label, description, allowMultiple, global, connectionType, clientId, clientSecret, authorizeUrl, accessTokenUrl, major, scopes, }) {
+export async function addConnectionDefinition({ token, devSlug, appId, key, label, description, global, connectionType, clientId, clientSecret, authorizeUrl, accessTokenUrl, major, scopes, }) {
     const connectionDefinitionId = uuid();
     const body = {
         connection_type: connectionType,
         slug: key,
         label,
         description,
-        allow_multiple: allowMultiple,
         global,
         major,
     };

package/lib/client/components/action.d.ts

@@ -1,11 +1,31 @@
 import React from "react";
 import { Icon } from "../icon";
 /**
- * Action Button
+ * An “action button” is a button that can appear in the Attio UI,
+ * typically on a record page.
+ *
+ * You must “register” the component that renders this component
+ * using `registerRecordAction()`.
  */
 export declare function Action(props: {
+    /**
+     * A function to execute when the button is clicked (or tapped)
+     */
     onTrigger: () => void;
+    /**
+     * An icon to display in the button, either an `AttioIcon` or
+     * a string `.png` referencing a file in your app’s `assets`
+     * directory.
+     *
+     * If no `icon` prop is provided, it will default to your app’s icon.
+     */
     icon?: Icon;
+    /**
+     * Whether or not the button is disabled. Defaults to `false`.
+     */
     disabled?: boolean;
+    /**
+     * The text content of the button.
+     */
     children: React.ReactNode;
 }): React.JSX.Element;

package/lib/client/components/multistep.d.ts

@@ -1,4 +1,9 @@
 import React from "react";
+/**
+ * A step in a multi-step component.
+ *
+ * @deprecated This is not ready for use yet.
+ */
 export interface Step {
     title: string;
     content: React.ReactNode;
@@ -6,6 +11,8 @@ export interface Step {
 }
 /**
  * A multi-step component
+ *
+ * @deprecated This is not ready for use yet.
  */
 export declare function Multistep(props: {
     initialStep?: number;

package/lib/client/components/row.d.ts

@@ -1,6 +1,9 @@
 import React from "react";
 /**
- * A component for laying children out horizontally.
+ * A component for laying out children horizontally.
+ *
+ * On the web, it can fit up to three children horizontally,
+ * and on mobile, all children will be presented vertically.
  */
 export declare function Row(props: {
     children: React.ReactNode;

package/lib/client/components/section.d.ts

@@ -1,8 +1,16 @@
 import React from "react";
 /**
- * A section of a page
+ * A section of a page with a title.
  */
 export declare function Section(props: {
+    /**
+     * The title of the section.
+     *
+     * It will be displayed in a stronger font than the content of the section.
+     */
     title: string;
+    /**
+     * The content of the section, either text or other components.
+     */
     children?: React.ReactNode;
 }): React.JSX.Element;

package/lib/client/components/text-block.d.ts

@@ -1,8 +1,14 @@
 import React from "react";
 /**
- * A text block
+ * A text block, whose content can optionally be aligned.
  */
 export declare function TextBlock(props: {
+    /**
+     * How to align the content of the text block.
+     */
     align?: "flex-start" | "flex-end" | "center" | "stretch" | "baseline" | "initial" | "inherit";
+    /**
+     * The content of the text block. Usually text, but can also be other components.
+     */
     children: React.ReactNode;
 }): React.JSX.Element;

package/lib/client/hooks/index.d.ts

@@ -1,4 +1,4 @@
-export { useDialog } from "./use-dialog.js";
 export { useAsyncCache, AsyncCacheConfig, AsyncFunction } from "./use-async-cache.js";
+export { useDialog } from "./use-dialog.js";
 export { useQuery } from "./use-query.js";
 export { useRecord } from "./use-record.js";

package/lib/client/hooks/use-async-cache.d.ts

@@ -12,8 +12,57 @@ export interface AsyncCacheConfig {
     [K: string]: AsyncFunction<Array<any>, any> | [AsyncFunction<Array<any>, any>, ...Array<any>];
 }
 /**
- * A hook that returns, and caches, the results of calling multiple async functions,
- * typically to load data.
+ * A hook that returns, and caches, the results of calling one or more async functions,
+ * typically to load data from a third party via server functions.
+ *
+ * The component it is used in will suspend until ALL async functions have resolved.
+ *
+ * ## EXAMPLE USAGE
+ *
+ * ----
+ * ```ts
+ * // load-widgets.server.ts
+ * export default async function loadWidgets() : Promise<Array<Widget>> {
+ *   // fetch widgets from somewhere
+ * }
+ * ```
+ * ----
+ * ```ts
+ * // load-sprockets.server.ts
+ * export default async function loadSprockets(
+ *   material: Material,
+ *   max?: number
+ * ): Promise<Array<Sprocket>> {
+ *   // fetch sprockets from somewhere
+ * }
+ * ```
+ * ----
+ * ```ts
+ * import { useAsyncCache } from "attio/client"
+ *
+ * import loadWidgets from "./load-widgets.server.ts"
+ * import loadSprockets from "./load-sprockets.server.ts"
+ *
+ * ...
+ *
+ * // inside component:
+ *
+ * const results = useAsyncCache({
+ *   // loadWidgets takes zero parameters and can thus be called without an array
+ *   widgets: loadWidgets,
+ *   // loadSprockets takes a `material` parameter, so we call it like this
+ *   ironSprockets: [loadSprockets, "iron"],
+ *   copperSprockets: [loadSprockets, "copper", 42],
+ * })
+ *
+ * const { widgets, ironSprockets, copperSprockets } = results.values
+ *
+ * ...
+ *
+ * // inside an event handler, perhaps, to refetch _only_ the iron sprockets
+ * results.invalidate("ironSprockets")
+ * ```
+ * ----
  */
 export declare function useAsyncCache<Config extends AsyncCacheConfig>(config: Config): {
     values: {

package/lib/client/hooks/use-dialog.d.ts

@@ -1,17 +1,71 @@
+import React from "react";
+/**
+ * Dialog component
+ *
+ * IMPORTANT: The <Dialog/> component should _always_ be rendered in your app.
+ * Do not render it conditionally.
+ */
+interface Dialog extends React.FC<{
+    /**
+     * A required title for the dialog.
+     */
+    title: string;
+    /**
+     * An optional callback that will be called when the dialog is closed.
+     */
+    onClose?: () => void;
+    /**
+     * The content of the dialog.
+     */
+    children: React.ReactNode;
+}> {
+}
 /**
  * This hook allows you to create a modal dialog.
  *
+ * ## EXAMPLE USAGE
+ *
+ * ----
+ * ```tsx
+ * import { useDialog } from "attio/client"
+ *
+ * ...
+ *
+ * // inside component:
+ * const dialog = useDialog()
+ *
+ * return (
+ *   <>
+ *     <Action onTrigger={() => dialog.open()}>Do Stuff</Action>
+ *     <dialog.Dialog>
+ *       Here is my useful UI
+ *     </dialog.Dialog>
+ *   </>
+ * )
+ * ```
+ * ----
+ *
  * @returns An object with the following properties:
  * - `Dialog`: A React component that you should render with the dialog contents as its children.
  * - `open`: Opens the rendered dialog.
  * - `close`: Closes the rendered dialog.
  */
 export declare function useDialog(): {
-    Dialog: React.ComponentType<{
-        title: string;
-        onClose?: () => void;
-        children: React.ReactNode;
-    }>;
+    /**
+     * The dialog component to render.
+     *
+     * IMPORTANT: The <Dialog/> component should _always_ be rendered in your app.
+     * Do not render it conditionally.
+     */
+    Dialog: Dialog;
+    /**
+     * A function to imperatively open the dialog. Often called via an
+     * `onTrigger` prop on an `<Action/>` button.
+     */
     open: () => void;
+    /**
+     * A function to imperatively close the dialog.
+     */
     close: () => void;
 };
+export {};

package/lib/client/hooks/use-query.d.ts

@@ -1,6 +1,47 @@
 import { Query } from "../run-query";
-export declare function useQuery<Variables extends Record<string, any>, Result>(
-/** GraphQL query */
-query: Query<Variables, Result>, 
-/** GraphQL query variables */
-variableValues?: Variables): Result;
+/**
+ * A hook that runs a GraphQL query and returns the result.
+ *
+ * Your component will suspend until the query completes.
+ *
+ * If you import the query from a `.graphql` file, and run `attio dev`,
+ * your query variables and result will be strongly typed.
+ *
+ * ## EXAMPLE USAGE
+ *
+ * ----
+ * ```graphql
+ * # get-person.graphql
+ * query getPerson($id: String!) {
+ *   workspace {
+ *     person(id: $id) {
+ *       name {
+ *         first
+ *         last
+ *       }
+ *     }
+ *   }
+ * }
+ * ```
+ * ----
+ * ```tsx
+ * // Component.tsx
+ * import { useQuery, useRecord } from "attio/client"
+ * import getPersonQuery from "./get-person.graphql"
+ *
+ * ...
+ *
+ * // in component:
+ * const { recordId } = useRecord()
+ * const result = useQuery(getPersonQuery, { id: recordId })
+ *
+ * const firstName : string | null = result.workspace?.person?.name?.first
+ * const lastName : string | null = result.workspace?.person?.name?.last
+ * ```
+ * ----
+ *
+ * @param query - The GraphQL query to run.
+ * @param variableValues - The variables to pass to the query.
+ * @returns The result of the query.
+ */
+export declare function useQuery<Variables extends Record<string, any> | never, Result>(query: Query<Variables, Result>, variableValues?: Variables extends never ? never : Variables): Result;

package/lib/client/hooks/use-record.d.ts

@@ -3,7 +3,12 @@ import { ObjectSlug } from "../object-slug.js";
  * Get information about the current record.
  */
 export declare function useRecord(): {
+    /**
+     * The ID of the current record.
+     */
     recordId: string;
+    /**
+     * The object type of the current record.
+     */
     object: ObjectSlug;
-    epithet: string;
 };

package/lib/client/register-record-action.d.ts

@@ -1,10 +1,28 @@
 import { ObjectSlug } from "./object-slug";
 /**
- * Registers an action for a record in Attio.
+ * Registers a component that renders an <Action/> button for a record in Attio.
+ *
+ * You should use this in your `app.tsx` file to register where you want your
+ * app to surface inside the Attio UI.
+ *
+ * ## EXAMPLE USAGE
+ *
+ * ----
+ * ```tsx
+ * // app.tsx
+ * import { registerRecordAction } from "attio/client";
+ * import { SendInvoiceButton } from "./send-invoice-button";
+ * import React from "react";
+ *
+ * registerRecordAction("send-invoice", <SendInvoiceButton />);
+ * ```
+ * ----
  */
 export declare function registerRecordAction(
 /**
  * The unique identifier for the action.
+ *
+ * It is only used internally; never shown to the user.
  */
 id: string, 
 /**

package/lib/client/run-query.d.ts

@@ -1,8 +1,52 @@
-/**
- * Imperatively runs a GraphQL query.
- */
-export declare function runQuery(query: string, variableValues?: Record<string, any>): Promise<any>;
-export type Query<Variables extends Record<string, any>, Result> = {
+export type Query<Variables extends Record<string, any> | never, Result> = {
     __data: Result;
     __variables: Variables;
 } & string;
+/**
+ * Imperatively runs a GraphQL query.
+ *
+ * If you import the query from a `.graphql` file, and run `attio dev`,
+ * your query variables and result will be strongly typed.
+ *
+ * ## EXAMPLE USAGE
+ *
+ * ----
+ * ```graphql
+ * # get-person.graphql
+ * query getPerson($id: String!) {
+ *   workspace {
+ *     person(id: $id) {
+ *       name {
+ *         first
+ *         last
+ *       }
+ *     }
+ *   }
+ * }
+ * ```
+ * ----
+ * ```tsx
+ * // get-person-name.ts
+ * import { runQuery } from "attio/client"
+ * import getPersonQuery from "./get-person.graphql"
+ *
+ * ...
+ *
+ * export async function getPersonName(id: string) : Promise<string> {
+ *   const person = await runQuery(getPersonQuery, { id })
+ *   const firstName: string | null = person.workspace?.person?.name?.first
+ *   const lastName: string | null = person.workspace?.person?.name?.last
+ *   return `${firstName ?? ""} ${lastName ?? ""}`
+ * }
+ * ```
+ * ----
+ *
+ * @param query - The GraphQL query to run.
+ * @param variableValues - The values of the variables to pass to the query.
+ * @returns A promise that resolves to the query result.
+ */
+export declare function runQuery<Variables extends Record<string, any>, Result>(
+/** GraphQL query */
+query: Query<Variables, Result> | string, 
+/** GraphQL query variables */
+variableValues?: Variables): Promise<Result>;

package/lib/commands/connection/add.js

@@ -29,7 +29,6 @@ export const options = z.object({
         .enum(["secret", "oauth2-code"])
         .optional()
         .describe(option({ description: "The type of connection to create" })),
-    allowMultiple: z.boolean().optional().default(false),
     authorizeUrl: z
         .string()
         .url("Invalid URL, e.g. https://authorization-server.com/authorize")
@@ -62,7 +61,7 @@ export const options = z.object({
         .default(false)
         .describe(option({ description: "Run in development mode (additional debugging info)" })),
 });
-export default function AddConnection({ options: { key, label, description, type: connectionType, authorizeUrl, accessTokenUrl, allowMultiple, scopes, clientId, clientSecret, dev, }, }) {
+export default function AddConnection({ options: { key, label, description, type: connectionType, authorizeUrl, accessTokenUrl, scopes, clientId, clientSecret, dev, }, }) {
     const [snapshot, send] = useMachine(addConnectionMachine, {
         input: {
             key,
@@ -71,7 +70,6 @@ export default function AddConnection({ options: { key, label, description, type
             connectionType,
             authorizeUrl,
             accessTokenUrl,
-            allowMultiple,
             scopes,
             clientId,
             clientSecret,
@@ -203,34 +201,6 @@ export default function AddConnection({ options: { key, label, description, type
                             { value: false, label: "An individual user" },
                             { value: true, label: "The entire workspace" },
                         ], onSelect: (global) => send({ type: "Choose Global", global }) })))),
-            snapshot.matches("Ask for allow multiple") && (React.createElement(React.Fragment, null,
-                React.createElement(Box, null,
-                    React.createElement(Text, null, snapshot.context.global
-                        ? `${snapshot.context.connectionType === "secret"
-                            ? "Secrets"
-                            : "Tokens"} should be:`
-                        : `A user should be able to:`)),
-                React.createElement(Box, null,
-                    React.createElement(Select, { items: [
-                            {
-                                value: false,
-                                label: snapshot.context.global
-                                    ? "Limited to one per workspace"
-                                    : `Create only one ${snapshot.context.connectionType === "secret"
-                                        ? "secret"
-                                        : "token"} that remains private`,
-                            },
-                            {
-                                value: true,
-                                label: snapshot.context.global
-                                    ? `Unlimited; users can add multiple ${snapshot.context.connectionType === "secret"
-                                        ? "secrets"
-                                        : "token"} to each workspace`
-                                    : `Create multiple ${snapshot.context.connectionType === "secret"
-                                        ? "secrets"
-                                        : "tokens"} and share them with other users`,
-                            },
-                        ], onSelect: (allowMultiple) => send({ type: "Choose Allow Multiple", allowMultiple }) })))),
             snapshot.matches("Ask for Authorize URL") && (React.createElement(React.Fragment, null,
                 React.createElement(Box, null,
                     React.createElement(Text, null, "e.g. https://authorization-server.com/oauth/authorize")),

package/lib/graphql/generate-operations.js

@@ -124,7 +124,9 @@ function generateOperationFunction(graphqlFileName, operationName, variableDefin
         return `${def.variable.name.value}: ${varTypeString}`;
     })
         .join(", ");
-    input = `export interface ${typeName}Variables { ${variables} }`;
+    input = variables
+        ? `export interface ${typeName}Variables { ${variables} }`
+        : `export type ${typeName}Variables = never`;
     return `
 declare module "./${graphqlFileName}" {
   ${input}

package/lib/machines/add-connection-machine.js

@@ -17,7 +17,7 @@ export const addConnectionMachine = setup({
         input: {},
     },
     actors: {
-        "createConnectionDefinition": fromCallback(({ sendBack, input: { developer: { token, slug: devSlug }, config, connectionType: connection_type, key, label, description, allowMultiple, global, authorizeUrl, accessTokenUrl, clientId, clientSecret, scopes, }, }) => {
+        "createConnectionDefinition": fromCallback(({ sendBack, input: { developer: { token, slug: devSlug }, config, connectionType: connection_type, key, label, description, global, authorizeUrl, accessTokenUrl, clientId, clientSecret, scopes, }, }) => {
             const add = async () => {
                 try {
                     await addConnectionDefinition({
@@ -29,7 +29,6 @@ export const addConnectionMachine = setup({
                         key,
                         label,
                         description,
-                        allowMultiple,
                         global,
                         accessTokenUrl,
                         authorizeUrl,
@@ -188,9 +187,6 @@ export const addConnectionMachine = setup({
         setGlobal: assign({
             global: (_, params) => params.global,
         }),
-        setAllowMultiple: assign({
-            allowMultiple: (_, params) => params.allowMultiple,
-        }),
         setAppConfig: assign({
             config: (_, params) => params.config,
         }),
@@ -215,7 +211,6 @@ export const addConnectionMachine = setup({
         "have client id": (_, params) => params.connectionType === "secret" ||
             options.shape.clientId.unwrap().safeParse(params.clientId?.trim()).success,
         "have global": (_, params) => params.global !== undefined,
-        "have allow multiple": (_, params) => params.allowMultiple !== undefined,
         "have client secret": (_, params) => params.connectionType === "secret" ||
             options.shape.clientSecret.unwrap().safeParse(params.clientSecret?.trim()).success,
         "is oauth": (_, params) => params.connectionType === "oauth2-code",
@@ -277,7 +272,6 @@ export const addConnectionMachine = setup({
                     clientId: context.clientId,
                     clientSecret: context.clientSecret,
                     global: context.global,
-                    allowMultiple: context.allowMultiple,
                     label: context.label,
                     description: context.description,
                     key: context.key,
@@ -310,7 +304,7 @@ export const addConnectionMachine = setup({
                         actions: { type: "setInvalidAuthorizeUrl", params: ({ context }) => context },
                     },
                 ],
-                "Previous": "Ask for allow multiple",
+                "Previous": "Ask for global",
                 "Next": {
                     target: "Ask for Access Token URL",
                     guard: { type: "have authorize url", params: ({ context }) => context },
@@ -564,25 +558,14 @@ export const addConnectionMachine = setup({
             ],
         },
         "Do we have global?": {
-            always: [
-                {
-                    target: "Do we have allow multiple?",
-                    guard: { type: "have global", params: ({ context }) => context },
-                },
-                {
-                    target: "Ask for global",
-                },
-            ],
-        },
-        "Do we have allow multiple?": {
             always: [
                 {
                     target: "Split on connection type",
-                    guard: { type: "have allow multiple", params: ({ context }) => context },
+                    guard: { type: "have global", params: ({ context }) => context },
                     reenter: true,
                 },
                 {
-                    target: "Ask for allow multiple",
+                    target: "Ask for global",
                 },
             ],
         },
@@ -629,28 +612,16 @@ export const addConnectionMachine = setup({
         "Ask for global": {
             on: {
                 "Choose Global": {
-                    target: "Do we have allow multiple?",
+                    target: "Split on connection type",
                     actions: { type: "setGlobal", params: ({ event }) => event },
+                    reenter: true,
                 },
                 "Previous": "Ask for description",
                 "Next": {
-                    target: "Ask for allow multiple",
-                    guard: { type: "have global", params: ({ context }) => context },
-                },
-            },
-        },
-        "Ask for allow multiple": {
-            on: {
-                "Choose Allow Multiple": {
                     target: "Split on connection type",
-                    actions: { type: "setAllowMultiple", params: ({ event }) => event },
+                    guard: { type: "have global", params: ({ context }) => context },
                     reenter: true,
                 },
-                "Previous": "Ask for global",
-                "Next": {
-                    target: "Split on connection type",
-                    guard: { type: "have allow multiple", params: ({ context }) => context },
-                },
             },
         },
     },

package/lib/machines/dev-machine.js

@@ -117,16 +117,7 @@ export const devMachine = setup({
             upload().catch((error) => sendBack({ type: "Upload Error", error }));
         }),
         "watch": fromCallback(({ sendBack }) => {
-            const watcher = chokidar.watch([
-                "src/app.tsx",
-                "src/app.jsx",
-                "src/app.ts",
-                "src/app.js",
-                "src/assets",
-                "src/webhooks",
-                "src/events",
-                ".env",
-            ], {
+            const watcher = chokidar.watch(["src", ".env"], {
                 ignored: "**/*.graphql.d.ts",
             });
             watcher.on("ready", () => watcher.on("all", () => {