SDK Integration

SDK Overview

The OK!Gotcha SDK provides a direct integration path for adding human approval workflows to your applications. It offers fine-grained control over approval processes and seamlessly integrates with your existing code.

npm install @okgotcha/sdk

Getting Started

Initialize the SDK

import { OkGotcha } from '@okgotcha/sdk';

// Initialize with API key from environment
const ok = OkGotcha({
  apiKey: process.env.OKGOTCHA_API_KEY
});

import { OkGotcha } from '@okgotcha/sdk';

// Initialize with API key from environment
const ok = OkGotcha({
  apiKey: process.env.OKGOTCHA_API_KEY
});

from okgotcha import OkGotcha

// Initialize with API key from environment
ok = OkGotcha(
  api_key=os.environ.get("OKGOTCHA_API_KEY")
)

We recommend storing your API key in environment variables rather than hardcoding it in your application.

Add Approval to Functions

The core functionality of OK!Gotcha is to add approval requirements to your functions:

// Original function
const deleteUser = async (userId: string): Promise<boolean> => {
  // Implementation to delete a user
  return true;
};

// Add approval requirement
const secureDeleteUser = ok.requireApproval({
  title: "User Deletion",
  description: "Permanently delete a user account",
  approvers: ["admin-team"]
})(deleteUser);

// Usage remains the same
try {
  const result = await secureDeleteUser("user-123");
  console.log("User deletion initiated, pending approval");
} catch (error) {
  console.error("Error:", error);
}

// Original function
const deleteUser = async (userId: string): Promise<boolean> => {
  // Implementation to delete a user
  return true;
};

// Add approval requirement
const secureDeleteUser = ok.requireApproval({
  title: "User Deletion",
  description: "Permanently delete a user account",
  approvers: ["admin-team"]
})(deleteUser);

// Usage remains the same
try {
  const result = await secureDeleteUser("user-123");
  console.log("User deletion initiated, pending approval");
} catch (error) {
  console.error("Error:", error);
}

# Using decorator syntax
@ok.require_approval(
    title="User Deletion",
    description="Permanently delete a user account",
    approvers=["admin-team"]
)
def delete_user(user_id: str) -> bool:
    # Implementation to delete a user
    return True

# Usage remains the same
try:
    result = delete_user("user-123")
    print("User deletion initiated, pending approval")
except Exception as e:
    print(f"Error: {e}")

When a function is wrapped with requireApproval, it will not execute immediately. Instead, it creates an approval request and returns a promise/future that resolves when approval is granted.

Handling Approval Results

There are multiple ways to handle the results of approval-required functions:

// Async/await pattern
try {
  const result = await secureFunction(arg1, arg2);
  console.log("Function executed with result:", result);
} catch (error) {
  if (error instanceof OkGotcha.RejectedError) {
    console.log("Function was rejected:", error.reason);
  } else if (error instanceof OkGotcha.ExpiredError) {
    console.log("Approval request expired");
  } else {
    console.error("Execution error:", error);
  }
}

// Async/await pattern
try {
  const result = await secureFunction(arg1, arg2);
  console.log("Function executed with result:", result);
} catch (error) {
  if (error instanceof OkGotcha.RejectedError) {
    console.log("Function was rejected:", error.reason);
  } else if (error instanceof OkGotcha.ExpiredError) {
    console.log("Approval request expired");
  } else {
    console.error("Execution error:", error);
  }
}

// Promise chaining
secureFunction(arg1, arg2)
  .then(result => {
    console.log("Function executed with result:", result);
  })
  .catch(error => {
    if (error instanceof OkGotcha.RejectedError) {
      console.log("Function was rejected:", error.reason);
    } else {
      console.error("Execution error:", error);
    }
  });

try:
    result = secure_function(arg1, arg2)
    print(f"Function executed with result: {result}")
except OkGotcha.RejectedError as e:
    print(f"Function was rejected: {e.reason}")
except OkGotcha.ExpiredError:
    print("Approval request expired")
except Exception as e:
    print(f"Execution error: {e}")

Advanced SDK Features

Check Approval Status

You can check the status of an approval request:

// Get the approval ID from the result of a requireApproval function
const { approvalId } = await secureFunction(arg1, arg2, { returnApprovalId: true });

// Check status
const status = await ok.getApprovalStatus(approvalId);
console.log("Current status:", status);

// Get the approval ID from the result of a requireApproval function
const { approvalId } = await secureFunction(arg1, arg2, { returnApprovalId: true });

// Check status
const status = await ok.getApprovalStatus(approvalId);
console.log("Current status:", status);

# Get the approval ID from the result of a require_approval function
approval_id = secure_function(arg1, arg2, return_approval_id=True)

# Check status
status = ok.get_approval_status(approval_id)
print(f"Current status: {status}")

Cancel Pending Approvals

You can cancel a pending approval request:

await ok.cancelApproval(approvalId, "No longer needed");

Webhook Notifications

Configure webhooks to receive real-time updates about approval status changes:

ok.configure({
  webhooks: {
    url: "https://your-server.com/webhooks/okgotcha",
    events: ["approval.created", "approval.approved", "approval.rejected"],
    secret: process.env.WEBHOOK_SECRET
  }
});

ok.configure({
  webhooks: {
    url: "https://your-server.com/webhooks/okgotcha",
    events: ["approval.created", "approval.approved", "approval.rejected"],
    secret: process.env.WEBHOOK_SECRET
  }
});

ok.configure(
  webhooks={
    "url": "https://your-server.com/webhooks/okgotcha",
    "events": ["approval.created", "approval.approved", "approval.rejected"],
    "secret": os.environ.get("WEBHOOK_SECRET")
  }
)

Next Steps

Learn about the MCP Integration option for LLM frameworks
Explore Audit Trails for logging and compliance
Set up Notifications for approval requests

Get Started

Core Concepts

Integration

Features

SDK Overview

Getting Started

Initialize the SDK

Add Approval to Functions

Handling Approval Results

Advanced SDK Features

Check Approval Status

Cancel Pending Approvals

Webhook Notifications

Next Steps

Get Started

Core Concepts

Integration

Features

​SDK Overview

​Getting Started

​Initialize the SDK

​Add Approval to Functions

​Handling Approval Results

​Advanced SDK Features

​Check Approval Status

​Cancel Pending Approvals

​Webhook Notifications

​Next Steps

SDK Overview

Getting Started

Initialize the SDK

Add Approval to Functions

Handling Approval Results

Advanced SDK Features

Check Approval Status

Cancel Pending Approvals

Webhook Notifications

Next Steps