feat: migrate samples repo into kittehub repo (#65)

Refs: ENG-1526

README.md

@@ -7,9 +7,8 @@ projects for:
 - Composable templates for interoperability between common services
 - Demonstrations of advanced system capabilities and features
 
-Go to the [samples](https://github.com/autokitteh/samples) repository to find
-more projects that demonstrate foundational system features, integration API
-details, and recommended practices.
+In addition, the [samples](./samples/) directory contains projects that
+demonstrate basic system features, integration APIs, and best practices.
 
 | Name                                                                             | Description                                                                              | Integrations                                |
 | :------------------------------------------------------------------------------- | :--------------------------------------------------------------------------------------- | :------------------------------------------ |

google_forms_to_jira/README.md

@@ -63,7 +63,7 @@ Google Forms:
 
 > [!TIP]
 > The exact CLI commands to do so (`ak connection init ...`) will appear in
-> the output of the `ak deploy` command from step 3 when you create the
+> the output of the `ak deploy` command from step 5 when you create the
 > project on the server, i.e. when you run that command for the first time.
 
 > [!IMPORTANT]

samples/README.md

@@ -0,0 +1,24 @@
+# Sample Projects
+
+This directory contains [AutoKitteh](https://github.com/autokitteh/autokitteh)
+projects that demonstrate basic system features, integration APIs, and best
+practices.
+
+- [Atlassian](./atlassian/)
+  - Confluence
+  - [Jira](./jira/)
+- [Discord](./discord/)
+- [GitHub](./github/)
+- [Google](./google/)
+  - [Calendar](./google/calendar/)
+  - Drive
+  - [Forms](./google/forms/)
+  - [Gmail](./google/gmail/)
+  - [Sheets](./google/sheets/)
+- [gRPC](./grpc/)
+- [HTTP](./http/)
+- [OpenAPI ChatGPT](./openai_chatgpt/)
+- [Runtime AutoKitteh event handling](./runtime_events/)
+- [Scheduler](./scheduler/)
+- [Slack](./slack/)
+- [Twilio](./twilio/)

samples/atlassian/README.md

@@ -0,0 +1,23 @@
+# Atlassian Samples
+
+These [AutoKitteh](https://github.com/autokitteh/autokitteh) projects
+demonstrate 2-way integration with Atlassian services and APIs.
+
+- Confluence
+- [Jira](./jira/)
+
+## Connection Notes
+
+AutoKitteh supports three connection modes:
+
+- User impersonation with:
+
+  - [API token](https://id.atlassian.com/manage-profile/security/api-tokens)
+    (available only in Atlassian Cloud)
+
+  - [Personal Access Token (PAT)](https://confluence.atlassian.com/enterprise/using-personal-access-tokens-1026032365.html)
+    (available only in on-prem servers)
+
+- [OAuth 2.0 (3LO) app](https://developer.atlassian.com/cloud/jira/platform/oauth-2-3lo-apps/)
+
+  - [AutoKitteh guide: configuring Atlassian integrations](https://docs.autokitteh.com/integrations/atlassian/config)

samples/atlassian/jira/README.md

@@ -0,0 +1,54 @@
+# Atlassian Jira Sample
+
+This [AutoKitteh](https://github.com/autokitteh/autokitteh) project
+demonstrates 2-way integration with
+[Jira](https://www.atlassian.com/software/jira/guides/).
+
+Jira API documentation:
+
+- [REST API](https://developer.atlassian.com/cloud/jira/platform/rest/v3/intro/)
+- ["Atlassian Python API" Python library](https://atlassian-python-api.readthedocs.io/)
+- ["Jira" Python library](https://jira.readthedocs.io/)
+
+Python code samples:
+
+- [Atlassian Python API](https://github.com/atlassian-api/atlassian-python-api/tree/master/examples/jira)
+- [Jira](https://github.com/pycontribs/jira/tree/main/examples)
+
+This program isn't meant to cover all available functions and events. It
+merely showcases a few illustrative, annotated, reusable examples.
+
+## Instructions
+
+1. Deploy the manifest file:
+
+   ```shell
+   ak deploy --manifest samples/jira/autokitteh.yaml
+   ```
+
+2. Follow the instructions in the `ak` CLI tool's output:
+
+   ```
+   Connection created, but requires initialization.
+   Please run this to complete:
+
+   ak connection init <connection ID>
+   ```
+
+3. Create a new issue in Jira, and check its comments
+
+## Connection Notes
+
+AutoKitteh supports three connection modes:
+
+- User impersonation with:
+
+  - [API token](https://id.atlassian.com/manage-profile/security/api-tokens)
+    (available only in Atlassian Cloud)
+
+  - [Personal Access Token (PAT)](https://confluence.atlassian.com/enterprise/using-personal-access-tokens-1026032365.html)
+    (available only in on-prem servers)
+
+- [OAuth 2.0 (3LO) app](https://developer.atlassian.com/cloud/jira/platform/oauth-2-3lo-apps/)
+
+  - [AutoKitteh guide: configuring Atlassian integrations](https://docs.autokitteh.com/integrations/atlassian/config)

samples/atlassian/jira/autokitteh.yaml

@@ -0,0 +1,20 @@
+# This YAML file is a declarative manifest that describes the setup
+# of an AutoKitteh project that demonstrates 2-way integration with
+# Atlassian Jira (https://www.atlassian.com/software/jira).
+
+version: v1
+
+project:
+  name: jira_sample
+  connections:
+    - name: jira_conn
+      integration: jira
+  triggers:
+    - name: jira_comment_created
+      connection: jira_conn
+      event_type: comment_created
+      call: program.py:on_jira_comment_created
+    - name: jira_issue_created
+      connection: jira_conn
+      event_type: issue_created
+      call: program.py:on_jira_issue_created

samples/atlassian/jira/program.py

@@ -0,0 +1,25 @@
+"""This program demonstrates AutoKitteh's 2-way Atlassian Jira integration.
+
+Atlassian Jira API documentation:
+- https://docs.autokitteh.com/integrations/atlassian/jira/python
+- https://docs.autokitteh.com/integrations/atlassian/jira/events
+"""
+
+from autokitteh.atlassian import jira_client
+
+
+def on_jira_issue_created(event):
+    issue_key = event.data.issue.key
+    user_name = event.data.user.displayName
+
+    jira = jira_client("jira_conn")
+    jira.issue_add_comment(issue_key, "This issue was created by " + user_name)
+
+
+def on_jira_comment_created(event):
+    issue_key = event.data.issue.key
+    comment = event.data.comment
+
+    jira = jira_client("jira_conn")
+    suffix = "\n\nThis comment was added by " + comment.author.displayName
+    jira.issue_edit_comment(issue_key, comment.id, comment.body + suffix)

samples/discord/README.md

@@ -0,0 +1,4 @@
+# Discord Samples
+
+These [AutoKitteh](https://github.com/autokitteh/autokitteh) projects
+demonstrate 2-way integration with [Discord](https://discord.com/).

samples/discord/discord_client/autokitteh.yaml

@@ -0,0 +1,19 @@
+# This YAML file is a declarative manifest that describes the setup
+# of an AutoKitteh project that demonstrates 2-way integration with
+# Discord (https://discord.com/).
+
+version: v1
+
+project:
+  name: discord_client_sample
+  vars:
+    - name: CHANNEL_ID
+      value: 
+  connections:
+    - name: discord_conn
+      integration: discord
+  triggers:
+    - name: start_event_loop
+      type: webhook
+      event_type: get
+      call: program.py:start_event_loop

samples/discord/discord_client/program.py

@@ -0,0 +1,70 @@
+"""
+This program demonstrates how to use Autokitteh's Discord integration to create a bot that performs basic operations.
+
+Modules:
+    - autokitteh.discord: Custom wrapper for the Discord API client.
+    - discord: The native Discord client API.
+
+Functions:
+    - on_ready: An asynchronous function that is triggered when the bot successfully connects to Discord.
+        It checks for the availability of a specified channel and sends a message if the channel is found.
+        Handles permission and HTTP-related exceptions when attempting to send the message.
+
+    - on_http_get: An AutoKitteh activity that runs the bot when an HTTP GET request is received.
+        Retrieves the bot token and initiates the bot connection.
+
+    - client.run(token): Starts the bot and connects it to the Discord gateway.
+        This function blocks execution until the bot is stopped. While running, the bot listens for and
+        responds to events, such as `on_ready`.
+
+        The `run` method initializes the event loop for the bot, connecting it to Discord using the specified token.
+        Once the connection is established, it triggers the `on_ready` event, allowing the bot to perform any
+        startup actions, such as checking for available channels and sending messages. This combination of
+        `run` and `on_ready` forms the backbone of the bot's lifecycle:
+            - `run` starts the bot and maintains the connection to Discord.
+            - `on_ready` is triggered automatically when the connection to Discord is fully established.
+
+Notes:
+    - This bot listens for the `on_ready` event to confirm a successful connection.
+    - The bot sends a "Meow!" message to the specified channel once connected.
+"""
+
+import os
+
+import autokitteh
+import autokitteh.discord as ak_discord
+import discord
+
+
+intents = discord.Intents.default()
+intents.message_content = True
+
+client = ak_discord.discord_client("discord_conn", intents)
+
+
+@autokitteh.activity
+def start_event_loop(event):
+    client.run(ak_discord.bot_token("discord_conn"))
+    return
+
+
+@client.event
+async def on_ready():
+    print(f"We have logged in as {client.user}")
+    channel_id = int(os.getenv("CHANNEL_ID"))
+    channel = client.get_channel(channel_id)
+
+    if channel is None:
+        print(f"Channel with ID {channel_id} not found")
+        print("Available channels:")
+        for guild in client.guilds:
+            for channel in guild.channels:
+                print(f"{channel.name} (ID: {channel.id})")
+        return
+
+    try:
+        await channel.send("Meow!")
+    except discord.Forbidden:
+        print("The bot does not have permission to send messages in this channel.")
+    except discord.HTTPException as e:
+        print(f"Failed to send message: {e}")

samples/discord/events/README.md

@@ -0,0 +1,62 @@
+# Discord Events
+
+This project demonstrates how to utilize AutoKitteh's event system for Discord, offering a simpler alternative to the [discord.py library](../discord_client/) when working with supported [events](https://docs.autokitteh.com/integrations/discord/events). The program listens for message-related events (message creation, update, and deletion) in Discord and logs the corresponding information. This example serves as a foundational guide for integrating AutoKitteh's Discord event handling with other services.
+
+## Benefits
+
+- **Simple Integration:** This workflow is designed to easily connect Discord to custom logging or processing systems.
+- **Modular Design:** You can extend or modify this program to suit your specific needs, such as adding more event types or integrating with external APIs.
+- **Open Source:** Feel free to modify and use this program in your own projects.
+
+## How It Works
+
+- **Message Events:** The program listens for three types of message events in Discord:
+  - `Message Create`: Captures when a message is sent and logs the username and message content.
+  - `Message Update`: Logs when a message is updated.
+  - `Message Delete`: Logs when a message is deleted.
+
+## Installation and Usage 
+
+1. Clone the Repository:
+
+   ```bash
+   git clone https://github.com/autokitteh/kittehub.git
+   cd kittehub/discord_message_logger
+   ```
+
+2. Install AutoKitteh:
+
+   Follow the installation guide for AutoKitteh:
+   [AutoKitteh Installation](https://docs.autokitteh.com/get_started/install)
+
+3. Configure Discord Integration:
+
+   Set up your Discord bot and connection using the documentation:
+   [Discord Integration Guide](https://docs.autokitteh.com/integrations/discord/connect)
+
+4. Run the AutoKitteh Server:
+
+   Run the following command to start the server:
+   ```bash
+   ak up --mode dev
+   ```
+
+5. Deploy the Project:
+
+   Apply the manifest and deploy the project:
+   ```bash
+   ak deploy --manifest autokitteh.yaml
+   ```
+
+   This command will output a connection ID for your Discord integration.
+
+6. Initialize the Connection:
+
+   Using the connection ID from the previous step, initialize the Discord connection:
+   ```bash
+   ak connection init discord_conn <connection ID>
+   ```
+
+7. Start Logging Discord Messages:
+
+   The workflow will be triggered automatically when a message-related event occurs in Discord.

samples/discord/events/autokitteh.yaml

@@ -0,0 +1,24 @@
+# This YAML file is a declarative manifest that describes the setup
+# of an AutoKitteh project that demonstrates 2-way integration with
+# Discord (https://discord.com/).
+
+version: v1
+
+project:
+  name: discord_events_sample
+  connections:
+    - name: discord_conn
+      integration: discord
+  triggers:
+    - name: discord_message_create
+      connection: discord_conn
+      event_type: message_create
+      call: program.py:on_discord_message_create
+    - name: discord_message_update
+      connection: discord_conn
+      event_type: message_update
+      call: program.py:on_discord_message_update
+    - name: discord_message_delete
+      connection: discord_conn
+      event_type: message_delete
+      call: program.py:on_discord_message_delete

samples/discord/events/program.py

@@ -0,0 +1,15 @@
+"""This program listens for message-related events in Discord and logs the corresponding information
+using the `autokitteh.discord` client.
+"""
+
+
+def on_discord_message_create(event):
+    print(f'User {event.data["author"]["username"]} sent: {event.data["content"]}')
+
+
+def on_discord_message_update(event):
+    print(f"Message updated to: {event.data['content']}")
+
+
+def on_discord_message_delete(event):
+    print(f"Message with ID {event.data['id']} was deleted")