Macro is a unified workspace for teams: email, chat, docs, tasks, agents, calls, and CRM — @-linked together with shared AI memory.
TypeScript agentaiai-agentsall-in-onecrmcrm-systememaillinearmcpmessagingnotesnotionofficerustslackslack-alternativestartupstartup-toolstypescriptworkspace
import { thrownResultErrorHasCode, throwOnErr } from '@core/util/result';
import { cognitionApiServiceClient } from '@service-cognition/client';
import type { Expiry } from '@service-cognition/generated/schemas/expiry';
import type { ProjectionStateResponse } from '@service-cognition/generated/schemas/projectionStateResponse';
import type { ProjectionStatus } from '@service-cognition/generated/schemas/projectionStatus';
import type { RefreshCadence } from '@service-cognition/generated/schemas/refreshCadence';
import type { TargetType } from '@service-cognition/generated/schemas/targetType';
import type { UpsertProjectionRequest } from '@service-cognition/generated/schemas/upsertProjectionRequest';
import { createConnectionWebsocketEffect } from '@service-connection/websocket';
import { queryOptions, useQuery, useQueryClient } from '@tanstack/solid-query';
import { type Accessor, createMemo, createSignal } from 'solid-js';
import { z } from 'zod';
const AI_PROJECTION_UPDATED_MESSAGE_TYPE = 'ai_projection_updated';
/** Gateway push sent when a projection materialization finishes (or errors).
* Mirrors `ProjectionStateResponse` plus the routing discriminators. */
type ProjectionUpdatedMessage = ProjectionStateResponse & {
type: typeof AI_PROJECTION_UPDATED_MESSAGE_TYPE;
target_type?: TargetType;
};
export const aiProjectionQueryKey = (id: string, targetType: TargetType) =>
['ai-projection', targetType, id] as const;
const GENERATING_STATUSES: ProjectionStatus[] = [
'cold',
'loading',
'refreshing',
];
/** Gateway pushes only land while a subscriber is mounted, so refetch fairly
* eagerly on remount (the POST is cheap: it returns the server-side cache and
* bumps the projection's keepalive). */
const PROJECTION_STALE_TIME = 30 * 1000;
export type CreateAIProjectionOptions<Schema extends z.ZodType = z.ZodType> = {
/** Frontend-defined projection id (e.g. `notification_important_widget`). */
id: string;
/** The prompt materialized by the projection. Changing the prompt (or
* `schema`/`model`) revises the projection server-side and regenerates. */
prompt: string;
/** Zod schema for structured output. When set, the projection result is
* generated as schema-conforming JSON (prompted, non-strict — works across
* providers) and `data` returns the parsed, validated object. */
schema?: Schema;
/** Optional `provider/model` id from `@core/component/AI/constant`.
* Defaults to the server's default model, which is premium-only. A free
* user's request must name a model in `FREE_MODELS`. */
model?: string;
/** Whether the projection targets the user or their team. Default `user`. */
targetType?: TargetType;
/** Background refresh cadence. Default `medium`. */
refreshCadence?: RefreshCadence;
/** How long the projection stays alive without being requested. Default `week`. */
expiry?: Expiry;
/** When true, a request that needs generation (cold cache or refresh)
* generates inline and resolves with the finished result instead of
* returning immediately and relying on the gateway push. Pair with a fast
* `model` for interactive use. */
awaitGeneration?: boolean;
/** Reactive enabled flag, like tanstack query's. Default true. */
enabled?: boolean;
};
/** Converts a zod schema into the non-strict JSON schema sent to the server. */
function toOutputSchema(schema: z.ZodType): Record<string, unknown> {
return z.toJSONSchema(schema, {
target: 'draft-07',
unrepresentable: 'throw',
cycles: 'throw',
reused: 'inline',
}) as Record<string, unknown>;
}
/** Builds the upsert request from one options snapshot. Schema conversion can
* throw, so callers run this inside the query function (or `refresh`) where
* the error surfaces through the query rather than during component setup. */
function buildProjectionRequest(
opts: CreateAIProjectionOptions<z.ZodType>,
overrides?: Partial<UpsertProjectionRequest>
): UpsertProjectionRequest {
return {
id: opts.id,
prompt: opts.prompt,
target_type: opts.targetType ?? 'user',
refresh_cadence: opts.refreshCadence ?? 'medium',
expiry: opts.expiry ?? 'week',
...(opts.model === undefined ? {} : { model: opts.model }),
...(opts.schema === undefined
? {}
: { output_schema: toOutputSchema(opts.schema) }),
await: opts.awaitGeneration ?? false,
...overrides,
};
}
// Cached past unmount: closes over the caller's plain options snapshot, not
// the options accessor, so an unmounted caller can be collected.
function aiProjectionQueryOptions(
queryKey: ReturnType<typeof aiProjectionQueryKey>,
opts: CreateAIProjectionOptions<z.ZodType>,
enabled: boolean
) {
return queryOptions({
queryKey,
queryFn: async () =>
throwOnErr(
async () =>
await cognitionApiServiceClient.upsertAiProjection(
buildProjectionRequest(opts)
)
),
enabled,
staleTime: PROJECTION_STALE_TIME,
});
}
function toProjectionState(
message: ProjectionUpdatedMessage
): ProjectionStateResponse {
return {
id: message.id,
status: message.status,
data: message.data,
error: message.error,
generated_at: message.generated_at,
stale_at: message.stale_at,
};
}
/**
* Materialized AI projection query, inspired by the Vercel AI SDK's
* `useObject` but backed by the server-side projection cache.
*
* - Upserting is reading: the query POSTs `/ai-projections`, which returns the
* cached result when warm and otherwise kicks off (or, with
* `awaitGeneration`, awaits) materialization.
* - Completion updates arrive over the connection gateway
* (`ai_projection_updated`) and are written straight into the query cache —
* no polling.
* - `refresh()` re-triggers generation even when a cached result exists; the
* stale data stays visible (`status: 'refreshing'`) until the new result
* lands.
*
* @example
* ```tsx
* const projection = createAIProjection(() => ({
* id: 'inbox/important',
* prompt: 'Summarize my most important unread emails.',
* schema: z.object({ items: z.array(z.string()) }),
* model: FREE_DEFAULT_MODEL,
* awaitGeneration: true,
* enabled: inboxOpen(),
* }));
*
* projection.data()?.items;
* <Button onClick={() => projection.refresh()} />
* ```
*/
export function createAIProjection<Schema extends z.ZodType>(
options: Accessor<CreateAIProjectionOptions<Schema>>
) {
const targetType = () => options().targetType ?? 'user';
const queryKey = () => aiProjectionQueryKey(options().id, targetType());
// Write through the same client the query observes so tests and hosts that
// provide their own QueryClient see refreshes and gateway pushes.
const queryClient = useQueryClient();
const query = useQuery(() =>
aiProjectionQueryOptions(
queryKey(),
options(),
(options().enabled ?? true) && !!options().id && !!options().prompt
)
);
// Materializations finish out-of-band (SQS worker or refresh sweeps); the
// gateway pushes the final state, which we write straight into the cache.
createConnectionWebsocketEffect((message) => {
if (message.type !== AI_PROJECTION_UPDATED_MESSAGE_TYPE) return;
let update: ProjectionUpdatedMessage;
try {
update = JSON.parse(message.data);
} catch {
console.error('unparsable ai projection update payload', message);
return;
}
if (update.id !== options().id) return;
if ((update.target_type ?? 'user') !== targetType()) return;
queryClient.setQueryData(queryKey(), toProjectionState(update));
});
/** Re-triggers generation even when a cached result exists. Resolves with
* the post-trigger state (`refreshing`, or the finished result when
* `awaitGeneration` is set). */
const [refreshError, setRefreshError] = createSignal<unknown>();
const refresh = async (): Promise<ProjectionStateResponse> => {
const key = queryKey();
try {
const state = await throwOnErr(
async () =>
await cognitionApiServiceClient.upsertAiProjection(
buildProjectionRequest(options(), { regenerate: true })
)
);
setRefreshError(undefined);
queryClient.setQueryData(key, state);
return state;
} catch (error) {
setRefreshError(error);
throw error;
}
};
// Do not suspend callers while the request is pending: they own the loading
// and timeout UI. Retain cached data during refreshes and refetch errors.
const state = () => (query.isPending ? undefined : query.data);
/** The projection result: schema-parsed object when a schema is set,
* otherwise the raw text. Undefined until a result exists (stale results
* remain visible while refreshing). */
const parsedResult = createMemo(
(): {
data: z.infer<Schema> | string | undefined;
error?: string;
} => {
const raw = state()?.data;
if (raw === null || raw === undefined) return { data: undefined };
const schema = options().schema;
if (!schema) return { data: raw };
let json: unknown;
try {
json = JSON.parse(raw);
} catch (error) {
console.error('ai projection result is not valid JSON', error);
return {
data: undefined,
error: 'AI projection result is not valid JSON',
};
}
const parsed = schema.safeParse(json);
if (!parsed.success) {
console.error(
'ai projection result failed schema validation',
parsed.error
);
return {
data: undefined,
error: 'AI projection result failed schema validation',
};
}
return { data: parsed.data };
}
);
const status = () => state()?.status;
return {
/** Parsed result (see above). */
data: () => parsedResult().data,
/** The projection lifecycle status (`cold`/`loading`/`ready`/...). */
status,
/** True while the initial fetch or a server-side generation is in flight. */
isGenerating: () => {
if (query.isLoading) return true;
const current = status();
return current !== undefined && GENERATING_STATUSES.includes(current);
},
/** Materialization error (from the projection) or request error message. */
error: () =>
state()?.error ??
query.error?.message ??
parsedResult().error ??
undefined,
/** The server refused the request for the user's plan (403). Repeating
* the same request fails the same way. */
isForbidden: () =>
thrownResultErrorHasCode(query.error, 'FORBIDDEN') ||
thrownResultErrorHasCode(refreshError(), 'FORBIDDEN'),
/** Re-trigger generation, keeping stale data visible meanwhile. */
refresh,
/** The underlying tanstack query, for advanced use. */
query,
};
}