@codesoul-co/hypha-memory / external-provider-operations

• Package index: @codesoul-co/hypha-memory
• Source: packages/memory/src/external-provider-operations.ts
• Exports: 10

Using this module

Use the External provider operations module for binding external or local providers to Hypha ports. It exports 2 classes, 1 constant, 4 functions, 2 interfaces, 1 type.

Import from the package entrypoint

import {
  InMemoryExternalProviderOperationStore,
  StructuredExternalProviderOperationStore,
  externalProviderOperationSchema,
  createExternalProviderOperation,
  externalProviderOperationId,
  fingerprintExternalOperationFailure,
  resolveExternalProviderOperationStore,
} from '@codesoul-co/hypha-memory';

import type {
  ExternalProviderOperation,
  ExternalProviderOperationStore,
  ExternalProviderOperationState,
} from '@codesoul-co/hypha-memory';

Usage patterns

• Use the 3 type/interface exports as static contracts in application code, adapters, or tests. Import them with import type; they do not exist at runtime.
• The module exposes 2 classes as constructable runtime implementations. Each symbol entry lists its constructor and public methods.
• The module exposes 4 functions as direct operation entrypoints. Every overload, required/optional parameter, and return type is documented below.
• The 1 constant/enum export provides stable values, schemas, definitions, or defaults. Reuse these exports instead of copying internal values into an application.

Public exports

Symbol	Kind	Signature	Description
InMemoryExternalProviderOperationStore	class	new InMemoryExternalProviderOperationStore(): InMemoryExternalProviderOperationStore	In Memory External Provider Operation Store class with 6 public constructor or member entries; its exact declarations are listed below.
StructuredExternalProviderOperationStore	class	new StructuredExternalProviderOperationStore(options: { store: StructuredStoreProvider; table?: string; }): StructuredExternalProviderOperationStore	Structured External Provider Operation Store class with 6 public constructor or member entries; its exact declarations are listed below.
externalProviderOperationSchema	constant	const externalProviderOperationSchema: ZodType<ExternalProviderOperation, ZodTypeDef, ExternalProviderOperation>	Runtime schema for External Provider Operation.
createExternalProviderOperation	function	createExternalProviderOperation(input: Omit<ExternalProviderOperation, "id" | "scopeHash" | "attempts" | "createdAt" | "updatedAt"> & { now?: string; }): ExternalProviderOperation	Create External Provider Operation function with 1 public call signature; parameters and return types are listed below.
externalProviderOperationId	function	externalProviderOperationId(providerId: string, operationId: string): string	External Provider Operation ID function with 1 public call signature; parameters and return types are listed below.
fingerprintExternalOperationFailure	function	fingerprintExternalOperationFailure(error: NormalizedMemoryError): string	Fingerprint External Operation Failure function with 1 public call signature; parameters and return types are listed below.
resolveExternalProviderOperationStore	function	resolveExternalProviderOperationStore(store: ExternalProviderOperationStore | undefined, profile: "production" | "test" | "ephemeral"): ExternalProviderOperationStore	Resolve External Provider Operation Store function with 1 public call signature; parameters and return types are listed below.
ExternalProviderOperation	interface	interface ExternalProviderOperation	External Provider Operation interface with 19 public fields or methods.
ExternalProviderOperationStore	interface	interface ExternalProviderOperationStore	External Provider Operation Store interface with 5 public fields or methods.
ExternalProviderOperationState	type	type ExternalProviderOperationState = 'pending' | 'running' | 'reconcile_required' | 'succeeded' | 'failed' | 'cancelled' | 'dead_letter'	Public type alias for External Provider Operation State; the declaration contains its complete type expression.

InMemoryExternalProviderOperationStore

In Memory External Provider Operation Store class with 6 public constructor or member entries; its exact declarations are listed below.

• Kind: class
• Import: import { InMemoryExternalProviderOperationStore } from '@codesoul-co/hypha-memory';
• Source module: external-provider-operations

Declaration

export declare class InMemoryExternalProviderOperationStore implements ExternalProviderOperationStore {
    readonly durability: "ephemeral";
    get(providerId: string, operationId: string): Promise<ExternalProviderOperation | null>;
    claim(operation: ExternalProviderOperation): Promise<{
            operation: ExternalProviderOperation;
            created: boolean;
        }>;
    set(operation: ExternalProviderOperation): Promise<void>;
    listRecoverable(providerId?: string, now?: string): Promise<ExternalProviderOperation[]>;
}

Public members

Member	Kind	Signature	Description
claim	method	claim(operation: ExternalProviderOperation): Promise<{ operation: ExternalProviderOperation; created: boolean; }>	Public method; parameters and return type are shown in the signature.
constructor	constructor	(): InMemoryExternalProviderOperationStore	Creates an instance of this class.
durability	property	readonly durability: "ephemeral"	Public property; its type, readonly modifier and optionality are shown in the signature.
get	method	get(providerId: string, operationId: string): Promise<ExternalProviderOperation | null>	Public method; parameters and return type are shown in the signature.
listRecoverable	method	listRecoverable(providerId?: string, now?: string): Promise<ExternalProviderOperation[]>	Public method; parameters and return type are shown in the signature.
set	method	set(operation: ExternalProviderOperation): Promise<void>	Public method; parameters and return type are shown in the signature.

StructuredExternalProviderOperationStore

Structured External Provider Operation Store class with 6 public constructor or member entries; its exact declarations are listed below.

• Kind: class
• Import: import { StructuredExternalProviderOperationStore } from '@codesoul-co/hypha-memory';
• Source module: external-provider-operations

Declaration

export declare class StructuredExternalProviderOperationStore implements ExternalProviderOperationStore {
    readonly durability: "durable";
    constructor(options: {
            store: StructuredStoreProvider;
            table?: string;
        });
    get(providerId: string, operationId: string): Promise<ExternalProviderOperation | null>;
    claim(operation: ExternalProviderOperation): Promise<{
            operation: ExternalProviderOperation;
            created: boolean;
        }>;
    set(operation: ExternalProviderOperation): Promise<void>;
    listRecoverable(providerId?: string, now?: string): Promise<ExternalProviderOperation[]>;
}

Public members

Member	Kind	Signature	Description
claim	method	claim(operation: ExternalProviderOperation): Promise<{ operation: ExternalProviderOperation; created: boolean; }>	Public method; parameters and return type are shown in the signature.
constructor	constructor	(options: { store: StructuredStoreProvider; table?: string; }): StructuredExternalProviderOperationStore	Creates an instance of this class.
durability	property	readonly durability: "durable"	Public property; its type, readonly modifier and optionality are shown in the signature.
get	method	get(providerId: string, operationId: string): Promise<ExternalProviderOperation | null>	Public method; parameters and return type are shown in the signature.
listRecoverable	method	listRecoverable(providerId?: string, now?: string): Promise<ExternalProviderOperation[]>	Public method; parameters and return type are shown in the signature.
set	method	set(operation: ExternalProviderOperation): Promise<void>	Public method; parameters and return type are shown in the signature.

externalProviderOperationSchema

Runtime schema for External Provider Operation.

• Kind: constant
• Import: import { externalProviderOperationSchema } from '@codesoul-co/hypha-memory';
• Source module: external-provider-operations

Declaration

export declare const externalProviderOperationSchema: ZodType<ExternalProviderOperation, ZodTypeDef, ExternalProviderOperation>;

createExternalProviderOperation

Create External Provider Operation function with 1 public call signature; parameters and return types are listed below.

• Kind: function
• Import: import { createExternalProviderOperation } from '@codesoul-co/hypha-memory';
• Source module: external-provider-operations

Declaration

export declare function createExternalProviderOperation(input: Omit<ExternalProviderOperation, 'id' | 'scopeHash' | 'attempts' | 'createdAt' | 'updatedAt'> & {
    now?: string;
}): ExternalProviderOperation;

Call signature

createExternalProviderOperation(input: Omit<ExternalProviderOperation, "id" | "scopeHash" | "attempts" | "createdAt" | "updatedAt"> & { now?: string; }): ExternalProviderOperation

Parameters

Parameter	Type	Required	Description
input	Omit<ExternalProviderOperation, "id" | "attempts" | "createdAt" | "updatedAt" | "scopeHash"> & { now?: string; }	Yes	Required parameter; accepted values are defined by the type column.

Returns

• Type: ExternalProviderOperation
• Description: The return contract is defined by the type shown above.

externalProviderOperationId

External Provider Operation ID function with 1 public call signature; parameters and return types are listed below.

• Kind: function
• Import: import { externalProviderOperationId } from '@codesoul-co/hypha-memory';
• Source module: external-provider-operations

Declaration

export declare function externalProviderOperationId(providerId: string, operationId: string): string;

Call signature

externalProviderOperationId(providerId: string, operationId: string): string

Parameters

Parameter	Type	Required	Description
providerId	string	Yes	Required parameter; accepted values are defined by the type column.
operationId	string	Yes	Required parameter; accepted values are defined by the type column.

Returns

• Type: string
• Description: The return contract is defined by the type shown above.

fingerprintExternalOperationFailure

Fingerprint External Operation Failure function with 1 public call signature; parameters and return types are listed below.

• Kind: function
• Import: import { fingerprintExternalOperationFailure } from '@codesoul-co/hypha-memory';
• Source module: external-provider-operations

Declaration

export declare function fingerprintExternalOperationFailure(error: NormalizedMemoryError): string;

Call signature

fingerprintExternalOperationFailure(error: NormalizedMemoryError): string

Parameters

Parameter	Type	Required	Description
error	NormalizedMemoryError	Yes	Required parameter; accepted values are defined by the type column.

Returns

• Type: string
• Description: The return contract is defined by the type shown above.

resolveExternalProviderOperationStore

Resolve External Provider Operation Store function with 1 public call signature; parameters and return types are listed below.

• Kind: function
• Import: import { resolveExternalProviderOperationStore } from '@codesoul-co/hypha-memory';
• Source module: external-provider-operations

Declaration

export declare function resolveExternalProviderOperationStore(store: ExternalProviderOperationStore | undefined, profile: 'production' | 'test' | 'ephemeral'): ExternalProviderOperationStore;

Call signature

resolveExternalProviderOperationStore(store: ExternalProviderOperationStore | undefined, profile: "production" | "test" | "ephemeral"): ExternalProviderOperationStore

Parameters

Parameter	Type	Required	Description
store	ExternalProviderOperationStore	Yes	Required parameter; accepted values are defined by the type column.
profile	"ephemeral" | "production" | "test"	Yes	Required parameter; accepted values are defined by the type column.

Returns

• Type: ExternalProviderOperationStore
• Description: The return contract is defined by the type shown above.

ExternalProviderOperation

External Provider Operation interface with 19 public fields or methods.

• Kind: interface
• Import: import type { ExternalProviderOperation } from '@codesoul-co/hypha-memory';
• Source module: external-provider-operations

Declaration

export interface ExternalProviderOperation {
    id: string;
    providerId: string;
    operationId: string;
    externalOperationId?: string;
    kind: 'mem0_event' | 'vertex_lro' | 'hindsight_operation' | 'unknown_write';
    state: ExternalProviderOperationState;
    scope: ManagedMemoryScope;
    scopeHash: string;
    profileRef: MemoryContractSpecRef;
    principal: {
        principalId: string;
        userId?: string;
    };
    attempts: number;
    deadlineAt?: string;
    nextAttemptAt?: string;
    cancellationRequestedAt?: string;
    failure?: NormalizedMemoryError;
    failureFingerprint?: string;
    createdAt: string;
    updatedAt: string;
    metadata?: Record<string, unknown>;
}

Contract members

Member	Kind	Signature	Description
attempts	property	attempts: number	Public property; its type, readonly modifier and optionality are shown in the signature.
cancellationRequestedAt	property	cancellationRequestedAt?: string	Public property; its type, readonly modifier and optionality are shown in the signature.
createdAt	property	createdAt: string	Public property; its type, readonly modifier and optionality are shown in the signature.
deadlineAt	property	deadlineAt?: string	Public property; its type, readonly modifier and optionality are shown in the signature.
externalOperationId	property	externalOperationId?: string	Public property; its type, readonly modifier and optionality are shown in the signature.
failure	property	failure?: NormalizedMemoryError	Public property; its type, readonly modifier and optionality are shown in the signature.
failureFingerprint	property	failureFingerprint?: string	Public property; its type, readonly modifier and optionality are shown in the signature.
id	property	id: string	Public property; its type, readonly modifier and optionality are shown in the signature.
kind	property	kind: "mem0_event" | "vertex_lro" | "hindsight_operation" | "unknown_write"	Public property; its type, readonly modifier and optionality are shown in the signature.
metadata	property	metadata?: Record<string, unknown>	Public property; its type, readonly modifier and optionality are shown in the signature.
nextAttemptAt	property	nextAttemptAt?: string	Public property; its type, readonly modifier and optionality are shown in the signature.
operationId	property	operationId: string	Public property; its type, readonly modifier and optionality are shown in the signature.
principal	property	principal: { principalId: string; userId?: string; }	Public property; its type, readonly modifier and optionality are shown in the signature.
profileRef	property	profileRef: MemoryContractSpecRef	Public property; its type, readonly modifier and optionality are shown in the signature.
providerId	property	providerId: string	Public property; its type, readonly modifier and optionality are shown in the signature.
scope	property	scope: ManagedMemoryScope	Public property; its type, readonly modifier and optionality are shown in the signature.
scopeHash	property	scopeHash: string	Public property; its type, readonly modifier and optionality are shown in the signature.
state	property	state: ExternalProviderOperationState	Public property; its type, readonly modifier and optionality are shown in the signature.
updatedAt	property	updatedAt: string	Public property; its type, readonly modifier and optionality are shown in the signature.

ExternalProviderOperationStore

External Provider Operation Store interface with 5 public fields or methods.

• Kind: interface
• Import: import type { ExternalProviderOperationStore } from '@codesoul-co/hypha-memory';
• Source module: external-provider-operations

Declaration

export interface ExternalProviderOperationStore {
    readonly durability: 'ephemeral' | 'durable';
    get(providerId: string, operationId: string): Promise<ExternalProviderOperation | null>;
    claim(operation: ExternalProviderOperation): Promise<{
        operation: ExternalProviderOperation;
        created: boolean;
    }>;
    set(operation: ExternalProviderOperation): Promise<void>;
    listRecoverable(providerId?: string, now?: string): Promise<ExternalProviderOperation[]>;
}

Contract members

Member	Kind	Signature	Description
claim	method	claim(operation: ExternalProviderOperation): Promise<{ operation: ExternalProviderOperation; created: boolean; }>	Public method; parameters and return type are shown in the signature.
durability	property	readonly durability: "ephemeral" | "durable"	Public property; its type, readonly modifier and optionality are shown in the signature.
get	method	get(providerId: string, operationId: string): Promise<ExternalProviderOperation | null>	Public method; parameters and return type are shown in the signature.
listRecoverable	method	listRecoverable(providerId?: string, now?: string): Promise<ExternalProviderOperation[]>	Public method; parameters and return type are shown in the signature.
set	method	set(operation: ExternalProviderOperation): Promise<void>	Public method; parameters and return type are shown in the signature.

ExternalProviderOperationState

Public type alias for External Provider Operation State; the declaration contains its complete type expression.

• Kind: type
• Import: import type { ExternalProviderOperationState } from '@codesoul-co/hypha-memory';
• Source module: external-provider-operations

Declaration

export type ExternalProviderOperationState = 'pending' | 'running' | 'reconcile_required' | 'succeeded' | 'failed' | 'cancelled' | 'dead_letter';