oso-cloud/dist/src/index.d.ts

Oso Cloud Node.js Client SDK

import { Api, type FactChangeset } from "./api";
import { QueryBuilder, QueryArgs } from "./query";
import { DefaultPolarTypes } from "./helpers";
import { ParityHandle } from "./parity-handle";
export { typedVar } from "./query";
export type Value = {
    type: string;
    id: string;
};
export type Values = [Value] | [Value, Value] | [Value, Value, Value] | [Value, Value, Value, Value] | [Value, Value, Value, Value, Value];
export type Fact = [string, ...Values];
/**
 * The type of values that can be converted into an Oso fact arg of type `V`. For example,
 * ```typescript
 * IntoValue<{ type: "Integer"; id: "123" }> =
 * ```
 * is equivalent to
 * ```typescript
 * { type: "Integer"; id: "123" } | 123
 * ```
 *
 * @param {Value} V
 */
export type IntoValue<V extends Value = Value> = V | ("String" extends V["type"] ? V["id"] : never) | ("Integer" extends V["type"] ? V["id"] extends `${infer N extends number | bigint}` ? N : number | bigint : never) | ("Boolean" extends V["type"] ? V["id"] extends `${infer B extends boolean}` ? B : boolean : never);
export type IntoValues<A extends Value[] = Values> = A extends [
    infer HD extends Value,
    ...infer TL extends Value[]
] ? [IntoValue<HD>, ...IntoValues<TL>] : [];
export type IntoFact<F extends Fact = Fact> = F extends [
    infer P extends string,
    ...infer A extends Value[]
] ? [P, ...IntoValues<A>] : never;
/**
 * The type of values that can query Oso fact arg of type `V`. For example,
 * ```typescript
 * IntoValueQuery<{ type: "Integer"; id: "123" }> =
 * ```
 * is equivalent to
 * ```typescript
 * { type: "Integer"; id: "123" } | 123 | { type?: "Integer" | null; id?: null } | null
 * ```
 *
 * @param {Value} V
 */
export type IntoValuePattern<V extends Value = Value> = IntoValue<V> | {
    type?: V["type"] | null;
    id?: null;
} | null;
export type IntoValuePatterns<A extends Value[] = Values> = A extends [
    infer HD extends Value,
    ...infer TL extends Value[]
] ? [IntoValuePattern<HD>, ...IntoValuePatterns<TL>] : [];
export type IntoFactPattern<F extends Fact = Fact> = F extends [
    infer P extends string,
    ...infer A extends Value[]
] ? [P, ...IntoValuePatterns<A>] : never;
export { AuthorizeResult } from "./api";
export declare enum LogLevel {
    error = "error",
    info = "info",
    debug = "debug"
}
export type LoggingFn = (level: LogLevel, msg: string, metadata: Record<string, any>) => void;
export type ClientOptions = {
    debug?: {
        print?: boolean;
        file?: string;
        logger?: LoggingFn;
    };
    userAgent?: string;
    fallbackUrl?: string;
    dataBindings?: string;
    fetchTimeoutMillis?: number;
    dnsServerEndpoints?: string[];
    fetchBuilder?: (fetch: (input: any, init?: any) => Promise<any>) => (input: any, init?: any) => Promise<any>;
};
export { ParityHandle } from "./parity-handle";
interface AuthorizeOptions<F extends Fact> {
    contextFacts?: IntoFact<F>[];
    parityHandle?: ParityHandle;
}
type AuthorizeArgs<F extends Fact, Q extends Fact> = Q extends [
    infer Allow,
    infer Actor extends Value,
    {
        type: infer String;
        id: infer Action;
    },
    infer Resource extends Value
] ? ["allow", "String"] extends [Allow, String] ? [
    IntoValue<Actor>,
    Action,
    IntoValue<Resource>,
    (IntoFact<F>[] | AuthorizeOptions<F>)?
] : never : never;
type ListArgs<F extends Fact, Q extends Fact> = Q extends [
    infer Allow,
    infer Actor extends Value,
    {
        type: infer String;
        id: infer Action;
    },
    {
        type: infer ResourceType;
        id: string;
    }
] ? ["allow", "String"] extends [Allow, String] ? [IntoValue<Actor>, Action, ResourceType, IntoFact<F>[]?] : never : never;
type ActionsArgs<F extends Fact, Q extends Fact> = Q extends [
    infer Allow,
    infer Actor extends Value,
    {
        type: infer String;
    },
    infer Resource extends Value
] ? ["allow", "String"] extends [Allow, String] ? [IntoValue<Actor>, IntoValue<Resource>, IntoFact<F>[]?] : never : never;
type ActionsResult<Q extends Fact, Args extends ActionsArgs<Fact, Fact>> = Q extends [
    infer Allow,
    Value,
    {
        type: infer String;
        id: infer Action;
    },
    Value
] ? ["allow", "String", Args] extends [Allow, String, ActionsArgs<Fact, Q>] ? Action : never : never;
type GetArgsArgs<A extends Value[]> = [] | (A extends [infer HD extends Value, ...infer TL extends Value[]] ? [IntoValuePattern<HD>, ...GetArgsArgs<TL>] : never);
type GetArgs<F extends Fact> = F extends [
    infer P extends string,
    ...infer A extends Value[]
] ? [P, ...GetArgsArgs<A>] : never;
type GetResult<F extends Fact, Args extends GetArgs<Fact>> = F extends unknown ? Args extends GetArgs<F> ? F : never : never;
type ActionsLocalArgs<F extends Fact, Q extends Fact> = Q extends [
    infer Allow,
    infer Actor extends Value,
    {
        type: infer String;
    },
    infer Resource extends Value
] ? ["allow", "String"] extends [Allow, String] ? [IntoValue<Actor>, IntoValue<Resource>, IntoFact<F>[]?] : never : never;
type AuthorizeLocalArgs<F extends Fact, Q extends Fact> = Q extends [
    infer Allow,
    infer Actor extends Value,
    {
        type: infer String;
        id: infer Action;
    },
    infer Resource extends Value
] ? ["allow", "String"] extends [Allow, String] ? [
    IntoValue<Actor>,
    Action,
    IntoValue<Resource>,
    (IntoFact<F>[] | AuthorizeOptions<F>)?
] : never : never;
type ListLocalArgs<F extends Fact, Q extends Fact> = Q extends [
    infer Allow,
    infer Actor extends Value,
    {
        type: infer String;
        id: infer Action;
    },
    {
        type: infer ResourceType;
    }
] ? ["allow", "String"] extends [Allow, String] ? [IntoValue<Actor>, Action, ResourceType, string, IntoFact<F>[]?] : never : never;
/**
 * Oso Cloud client
 *
 * For more detailed documentation, see
 * https://www.osohq.com/docs/app-integration/client-apis/node
 */
export declare class Oso<PT extends DefaultPolarTypes = DefaultPolarTypes> {
    api: Api;
    constructor(url: string, apiKey: string, options?: ClientOptions);
    /**
     * Check a permission.
     *
     * @param {IntoValue} actor
     * @param {string} action
     * @param {IntoValue} resource
     * @param {IntoFact[]} [contextFacts]
     * @param {ParityHandle} parityHandle
     * @returns {Promise<boolean>}
     */
    authorize(...[actor, action, resource, authArgOptions]: AuthorizeArgs<PT["fact"], PT["query"]>): Promise<boolean>;
    /**
     * List authorized resources:
     *
     * Fetches a list of resource ids on which an actor can perform a particular action.
     *
     * @param {IntoValue} actor
     * @param {string} action
     * @param {string} resourceType
     * @param {IntoFact[]} [contextFacts]
     * @returns {Promise<string[]>}
     */
    list(...[actor, action, resourceType, contextFacts]: ListArgs<PT["fact"], PT["query"]>): Promise<string[]>;
    /**
     * List authorized actions:
     *
     * Fetches a list of actions which an actor can perform on a particular resource.
     *
     * @param {IntoValue} actor
     * @param {IntoValue} resource
     * @param {IntoFact[]} [contextFacts]
     * @returns {Promise<string[]>}
     */
    actions<Args extends ActionsArgs<PT["fact"], PT["query"]>>(...[actor, resource, contextFacts]: Args): Promise<ActionsResult<PT["query"], Args>[]>;
    /**
     * Update the active policy:
     *
     * Updates the policy in Oso Cloud. The string passed into this method should be
     * written in Polar.
     *
     * NOTE: If you're using types generated from your policy, it's recommended that you
     * avoid this method in production, as updating your policy will likely
     * affect the set of generated types. Instead, use the Oso Cloud CLI to
     * manage your policy and generate new types.
     *
     * @param {string} src
     */
    policy(src: string): Promise<void>;
    /**
     * Returns metadata about the currently active policy
     */
    getPolicyMetadata(): Promise<import("./api").PolicyMetadata>;
    /**
     * Get facts:
     *
     * Get facts that are stored in Oso Cloud. Can be used to check the existence
     * of a particular fact, or used to fetch all facts that have a particular
     * argument.
     *
     * `oso.get()` only returns facts you've added. If you want to return a list of authorized resources, use
     * the Check API. For example, to answer "on which resouces can a given user
     * perform a given action", use `oso.list()`.
     *
     * @param {IntoFactPattern} fact
     * @returns {Promise<Fact[]>}
     */
    get<Args extends GetArgs<PT["fact"]>>([predicate, ...args]: Args): Promise<GetResult<PT["fact"], Args>[]>;
    /**
     * Fetches a query that can be run against your database to determine the actions
     * an actor can perform on a resource.
     *
     * Returns a SQL query to run against the local database.
     *
     * @param {IntoValue} actor
     * @param {IntoValue} resource
     * @param {IntoFact[]?} contextFacts
     * @returns {Promise<string>}
     */
    actionsLocal(...[actor, resource, contextFacts]: ActionsLocalArgs<PT["fact"], PT["query"]>): Promise<string>;
    /**
     * Check a permission depending on data both in Oso Cloud and stored in a local database.
     *
     * Returns a SQL query to run against the local database.
     *
     * @param {IntoValue} actor
     * @param {string} action
     * @param {IntoValue} resource
     * @param {IntoFact[]?} contextFacts
     * @returns {Promise<string>}
     */
    authorizeLocal(...[actor, action, resource, authArgOptions]: AuthorizeLocalArgs<PT["fact"], PT["query"]>): Promise<string>;
    /**
     * List authorized resources depending on data both in Oso Cloud and stored in a local database.
     *
     * Returns a SQL query to run against the local database.
     *
     * @param {IntoValue} actor
     * @param {string} action
     * @param {string} resourceType
     * @param {string} column
     * @param {IntoFact[]?} contextFacts
     * @returns {Promise<string>}
     */
    listLocal(...[actor, action, resourceType, column, contextFacts]: ListLocalArgs<PT["fact"], PT["query"]>): Promise<string>;
    /**
     * Query for an arbitrary expression.
     * Use `typedVar` to create variables to use in the query,
     * and refer to them in the final `evaluate` call to get their values.
     *
     * @param query
     * @returns {QueryBuilder}
     */
    buildQuery(query: QueryArgs<PT["fact"] | PT["query"]>): QueryBuilder<PT>;
    /**
     * Add a fact:
     *
     * Adds a fact with the given predicate and arguments.
     *
     * @param {IntoFact} fact
     */
    insert(fact: IntoFact<PT["fact"]>): Promise<void>;
    /**
     * Delete fact:
     *
     * Deletes a fact. Does not throw an error if the fact is not found.
     * You can use `null` as a wildcard argument.
     *
     * @param {IntoFactPattern} fact
     */
    delete(fact: IntoFactPattern<PT["fact"]>): Promise<void>;
    /**
     * Transactionally delete and add facts:
     *
     * Allows deleting and inserting many facts in one atomic transaction.
     * Deletions and insertions are run in the order they appear in the closure.
     *
     * @param {(tx: BatchTransaction) => void | Promise<void>} f - the callback which runs the `insert`s and `delete`s.
     *   These changes can be issued via `tx.insert(fact)` and `tx.delete(fact)` within the closure.
     */
    batch(f: (tx: BatchTransaction<PT>) => void | Promise<void>): Promise<void>;
}
declare class BatchTransaction<PT extends DefaultPolarTypes> {
    changes: FactChangeset[];
    constructor();
    /**
     * Add a fact:
     *
     * Adds a fact with the given predicate and arguments.
     *
     * @param {IntoFact} fact
     */
    insert(fact: IntoFact<PT["fact"]>): void;
    /**
     * Delete fact:
     *
     * Deletes a fact. Does not throw an error if the fact is not found.
     * You can use `null` as a wildcard argument.
     *
     * @param {IntoFactPattern} fact
     */
    delete(fact: IntoFactPattern<PT["fact"]>): void;
}
//# sourceMappingURL=index.d.ts.map