SimplyStack Documentation

Installation

Install the SimplyStack SDK from npm:

npm install @simplystack-org/sdk

import { SimplyStackSDK } from "@simplystack-org/sdk";

// Initialize the SDK with just your API key
const sdk = new SimplyStackSDK("your-api-key-here");

💡 Pro Tip

Store your API key in environment variables for security. Never commit API keys to version control.

Authentication

SimplyStack uses API key authentication with automatic project scoping. Each API key is associated with a specific project.

Getting Your API Key

Navigate to your project in the SimplyStack dashboard
Go to Settings → API Keys
Click Generate New API Key
Copy the generated key and store it securely

Environment Variables

Create a .env.local file in your project root:

# .env.local
SIMPLYSTACK_API_KEY=your_api_key_here

Then use it in your application:

// Most common usage - SDK connects to SimplyStack automatically
const sdk = new SimplyStackSDK(process.env.SIMPLYSTACK_API_KEY!);

// For local development with custom URL (optional)
const sdk = new SimplyStackSDK(
  process.env.SIMPLYSTACK_API_KEY!
);

⚠️ Security Note

API keys provide full access to your project. Keep them secure and never expose them in client-side code.

Your First API Call

Let's start by creating a simple blog post to verify your setup is working correctly.

Basic Example

import { SimplyStackSDK } from "@simplystack-org/sdk";

async function createFirstPost() {
  // Initialize SDK with just your API key
  const sdk = new SimplyStackSDK(process.env.SIMPLYSTACK_API_KEY!);

  // Create a blog post
  const { data: post, error } = await sdk.createBlogPost({
    title: "My First Post",
    content: `
      <h1>Welcome to SimplyStack!</h1>
      <p>This is my first blog post created with the SimplyStack SDK.</p>
      <p>Created at: ${new Date().toISOString()}</p>
    `,
    excerpt: "My first post using SimplyStack",
    tags: ["getting-started", "first-post"],
    meta_title: "My First Post - SimplyStack Demo",
    meta_description: "Learning how to use SimplyStack SDK"
  });

  if (error) {
    console.error("Failed to create post:", error);
    return;
  }

  console.log("Post created successfully:", post);
  return post;
}

// Call the function
createFirstPost();

Response Format

All SDK methods return a consistent response format with either data or an error:

// Success response
{
  data: {
    id: "f1fc1bb3-b9a8-4172-8637-755105bae373",
    title: "My First Post",
    content: "<h1>Welcome to SimplyStack!</h1>...",
    tags: ["getting-started", "first-post"],
    project_id: "aa9af817-0f46-4d28-a8b6-b6c22e4f44d9",
    user_id: null,
    created_at: "2025-05-25T02:48:41.902157+00:00",
    updated_at: "2025-05-25T02:48:41.902157+00:00"
  }
}

// Error response
{
  error: "Authentication failed: Invalid API key"
}

Error Handling Best Practices

async function safeApiCall() {
  const sdk = new SimplyStackSDK(process.env.SIMPLYSTACK_API_KEY!);

  try {
    const { data: posts, error } = await sdk.getBlogPosts();

    if (error) {
      // Handle API errors
      console.error("API Error:", error);
      
      // You might want to show user-friendly messages
      if (error.includes("Authentication")) {
        throw new Error("Please check your API key");
      }
      
      throw new Error(`Failed to fetch posts: ${error}`);
    }

    // Use data safely
    console.log(`Found ${posts?.length || 0} posts`);
    return posts || [];

  } catch (error) {
    // Handle network or other errors
    console.error("Unexpected error:", error);
    throw error;
  }
}

Testing Your Setup

Here's a complete test script you can run to verify everything is working:

// test-setup.ts
import { SimplyStackSDK } from "@simplystack-org/sdk";

async function testSetup() {
  console.log("🧪 Testing SimplyStack SDK setup...");
  
  const sdk = new SimplyStackSDK(
    process.env.SIMPLYSTACK_API_KEY
  );

  try {
    // Test 1: Get project info
    console.log("1. Testing project access...");
    const { data: projects, error: projectError } = await sdk.getProjects();
    
    if (projectError) {
      throw new Error(`Project access failed: ${projectError}`);
    }
    
    console.log("✅ Project access successful");
    console.log(`   Project: ${projects?.[0]?.name}`);

    // Test 2: Create a test blog post
    console.log("2. Testing blog post creation...");
    const { data: post, error: postError } = await sdk.createBlogPost({
      title: "SDK Test Post",
      content: "<p>This is a test post to verify SDK functionality.</p>",
      tags: ["test", "sdk-verification"]
    });

    if (postError) {
      throw new Error(`Blog post creation failed: ${postError}`);
    }

    console.log("✅ Blog post creation successful");
    console.log(`   Post ID: ${post?.id}`);

    // Test 3: Fetch the created post
    console.log("3. Testing blog post retrieval...");
    const { data: retrievedPost, error: retrieveError } = await sdk.getBlogPost(post!.id);

    if (retrieveError) {
      throw new Error(`Blog post retrieval failed: ${retrieveError}`);
    }

    console.log("✅ Blog post retrieval successful");

    // Test 4: Clean up - delete test post
    console.log("4. Cleaning up test data...");
    const { error: deleteError } = await sdk.deleteBlogPost(post!.id);

    if (deleteError) {
      console.warn(`⚠️ Failed to delete test post: ${deleteError}`);
    } else {
      console.log("✅ Test cleanup successful");
    }

    console.log("🎉 All tests passed! Your SimplyStack setup is working correctly.");

  } catch (error) {
    console.error("❌ Setup test failed:", error);
    process.exit(1);
  }
}

testSetup();

Run this test with:

npx ts-node test-setup.ts

Next Steps

Now that you have SimplyStack set up and working, here's what you can explore next:

Getting Started