​
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
});

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);
}

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);
  }
}

​
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);

​
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
  }
});

​
Next Steps